# Gogs MCP Server

A Model Context Protocol (MCP) server that provides access to Gogs git hosting APIs. This server enables AI assistants like Claude to interact with Gogs repositories, users, and other resources.

## Features

This MCP server provides tools to:

- **User Management**
  - Get authenticated user information
  - Get specific user details
  - Search for users

- **Repository Management**
  - List user repositories
  - Search repositories
  - Get repository information
  - Create new repositories
  - Delete repositories

- **Content Access**
  - Get file and directory contents
  - Get raw file content
  - List repository branches
  - Get commit history
  - Get git trees (low-level repository structure access)

- **Issue Management**
  - List issues in a repository
  - Get specific issue details
  - Create new issues
  - Update existing issues (including state changes)
  - List comments on issues
  - Add comments to issues
  - Edit existing comments

- **Label Management**
  - List all labels in a repository
  - Get specific label details
  - Create new labels
  - Update existing labels
  - Delete labels
  - List labels on an issue
  - Add labels to an issue
  - Remove labels from an issue
  - Replace all labels on an issue
  - Remove all labels from an issue

- **Organization Management**
  - List organizations for authenticated user
  - Create new organization
  - List public organizations for a user
  - Get organization details
  - Update organization information
  - Add/update organization member with role

- **Team Management**
  - List teams in an organization
  - Create new team
  - Get team details
  - Add member to a team
  - Remove member from a team

- **Release Management**
  - List releases for a repository

## Installation

### Prerequisites

- Node.js 18 or higher
- npm or yarn
- A Gogs server instance
- Gogs access token (optional, but recommended for authenticated access)

**OR**

- Docker and Docker Compose (for containerized deployment)

### Setup

1. Clone this repository:
   ```bash
   git clone ssh://git@207.154.220.231:10022/claude/gogs-mcp.git
   cd gogs-mcp
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Build the project:
   ```bash
   npm run build
   ```

### Docker Setup

1. Clone this repository:
   ```bash
   git clone ssh://git@207.154.220.231:10022/claude/gogs-mcp.git
   cd gogs-mcp
   ```

2. Create a `.env` file from the example:
   ```bash
   cp .env.example .env
   ```

3. Edit `.env` and configure your Gogs server URL and access token:
   ```bash
   GOGS_SERVER_URL=https://your-gogs-server.com
   GOGS_ACCESS_TOKEN=your-access-token-here
   ```

4. Build and run with Docker Compose:
   ```bash
   docker-compose up -d
   ```

   Or build the Docker image manually:
   ```bash
   docker build -t gogs-mcp-server .
   docker run --env-file .env gogs-mcp-server
   ```

## Configuration

### Generate Gogs Access Token

1. Log in to your Gogs instance
2. Navigate to Settings → Applications
3. Create a new access token with appropriate permissions
4. Copy the token for use in configuration

### Environment Variables

Create a `.env` file or set environment variables:

```bash
GOGS_SERVER_URL=https://your-gogs-server.com
GOGS_ACCESS_TOKEN=your-access-token-here

# Transport mode (optional, default: stdio)
TRANSPORT_MODE=stdio  # or 'http' for HTTP/SSE transport

# HTTP server configuration (only used when TRANSPORT_MODE=http)
HTTP_PORT=3000
HTTP_HOST=0.0.0.0
```

The access token is optional but recommended. Without it:
- User email fields may be empty (anti-spam measure)
- Some operations requiring authentication will fail
- Only public repositories will be accessible

### Transport Modes

The server supports two transport modes:

**stdio (default)**: For use with MCP clients like Claude Desktop
- Communicates via standard input/output
- Runs as a subprocess of the MCP client
- Suitable for desktop applications

**http**: For HTTP-based access with Server-Sent Events (SSE)
- Exposes HTTP endpoints for the MCP protocol
- Runs as a standalone web server
- Suitable for web applications and remote access
- Supports CORS for cross-origin requests

## Usage

### With Claude Desktop (stdio mode)

Add the server to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "gogs": {
      "command": "node",
      "args": ["/absolute/path/to/gogs-mcp-server/dist/index.js"],
      "env": {
        "GOGS_SERVER_URL": "https://your-gogs-server.com",
        "GOGS_ACCESS_TOKEN": "your-access-token-here",
        "TRANSPORT_MODE": "stdio"
      }
    }
  }
}
```

### HTTP Mode

To run the server in HTTP mode for web applications:

1. Set the transport mode to HTTP in your `.env` file:
   ```bash
   TRANSPORT_MODE=http
   HTTP_PORT=3000
   HTTP_HOST=0.0.0.0
   ```

2. Start the server:
   ```bash
   npm start
   ```

3. The server will be available at:
   - SSE endpoint: `http://localhost:3000/sse`
   - Message endpoint: `http://localhost:3000/message`
   - Health check: `http://localhost:3000/health`

4. Connect your MCP client to the SSE endpoint to establish a persistent connection.

### HTTP Mode with Docker

```bash
# Set environment variables in .env
TRANSPORT_MODE=http
HTTP_PORT=3000

# Run with docker-compose
docker-compose up -d

# Or run with Docker directly
docker run -p 3000:3000 \
  -e GOGS_SERVER_URL=https://your-gogs-server.com \
  -e GOGS_ACCESS_TOKEN=your-access-token-here \
  -e TRANSPORT_MODE=http \
  -e HTTP_PORT=3000 \
  gogs-mcp-server:latest
```

### With Other MCP Clients (stdio mode)

The server uses stdio transport and can be integrated with any MCP-compatible client:

```bash
# Set environment variables
export GOGS_SERVER_URL=https://your-gogs-server.com
export GOGS_ACCESS_TOKEN=your-access-token-here
export TRANSPORT_MODE=stdio

# Run the server
npm start
```

### With Docker

You can use the Docker image with MCP clients by mounting it as a command:

```json
{
  "mcpServers": {
    "gogs": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "GOGS_SERVER_URL=https://your-gogs-server.com",
        "-e", "GOGS_ACCESS_TOKEN=your-access-token-here",
        "gogs-mcp-server:latest"
      ]
    }
  }
}
```

Or using docker-compose:

```json
{
  "mcpServers": {
    "gogs": {
      "command": "docker-compose",
      "args": [
        "-f", "/absolute/path/to/gogs-mcp-server/docker-compose.yml",
        "run",
        "--rm",
        "gogs-mcp-server"
      ]
    }
  }
}
```

## Available Tools

### User Tools

#### `get_current_user`
Get information about the authenticated user.

#### `get_user`
Get information about a specific user.
- `username` (string, required): Username to look up

#### `search_users`
Search for users by username.
- `query` (string, required): Search query
- `limit` (number, optional): Maximum results (default: 10)

### Repository Tools

#### `list_user_repositories`
List repositories for a user.
- `username` (string, optional): Username (omit for authenticated user)

#### `search_repositories`
Search for repositories.
- `query` (string, required): Search query
- `uid` (number, optional): User ID to filter by
- `limit` (number, optional): Maximum results (default: 10)
- `page` (number, optional): Page number (default: 1)

#### `get_repository`
Get information about a specific repository.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name

#### `create_repository`
Create a new repository.
- `name` (string, required): Repository name
- `description` (string, optional): Repository description
- `private` (boolean, optional): Create as private (default: false)
- `auto_init` (boolean, optional): Initialize with README (default: false)
- `gitignores` (string, optional): Gitignore templates (e.g., "Go,VisualStudioCode")
- `license` (string, optional): License template (e.g., "MIT License")
- `readme` (string, optional): README template (default: "Default")

#### `delete_repository`
Delete a repository (requires admin access).
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name

### Content Tools

#### `get_contents`
Get file or directory contents from a repository.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `path` (string, required): File or directory path
- `ref` (string, optional): Branch, tag, or commit SHA (default: default branch)

#### `get_raw_content`
Get raw file content from a repository.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `ref` (string, required): Branch, tag, or commit SHA
- `path` (string, required): File path

#### `list_branches`
List all branches in a repository.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name

#### `get_commits`
Get commit history from a repository.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `sha` (string, optional): Branch name or commit SHA
- `page` (number, optional): Page number (default: 1)

#### `get_tree`
Get a git tree by SHA - provides low-level access to repository structure at a specific commit or tree SHA. Returns tree entries including files (blobs), directories (trees), and submodules (commits) with their modes and permissions.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `sha` (string, required): Git tree SHA or commit SHA

### Issue Management Tools

#### `list_issues`
List issues in a repository.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `state` (string, optional): Filter by state - 'open', 'closed', or 'all' (default: 'open')
- `labels` (string, optional): Comma-separated list of label names
- `page` (number, optional): Page number (default: 1)
- `per_page` (number, optional): Results per page (default: 30)

#### `get_issue`
Get a specific issue by number.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `number` (number, required): Issue number

#### `create_issue`
Create a new issue in a repository.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `title` (string, required): Issue title
- `body` (string, optional): Issue description
- `assignee` (string, optional): Username to assign the issue to
- `milestone` (number, optional): Milestone ID
- `labels` (array of numbers, optional): Array of label IDs

#### `update_issue`
Update an existing issue (including closing or reopening).
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `number` (number, required): Issue number
- `title` (string, optional): Issue title
- `body` (string, optional): Issue description
- `assignee` (string, optional): Username to assign the issue to
- `milestone` (number, optional): Milestone ID
- `state` (string, optional): Issue state - 'open' or 'closed'
- `labels` (array of numbers, optional): Array of label IDs

#### `list_issue_comments`
List all comments on an issue.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `number` (number, required): Issue number

#### `create_issue_comment`
Add a comment to an issue.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `number` (number, required): Issue number
- `body` (string, required): Comment text

#### `update_issue_comment`
Edit an existing comment on an issue.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `commentId` (number, required): Comment ID
- `body` (string, required): Updated comment text

### Label Management Tools

#### `list_labels`
List all labels in a repository.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name

#### `get_label`
Get a specific label by ID.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `labelId` (number, required): Label ID

#### `create_label`
Create a new label in a repository.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `name` (string, required): Label name
- `color` (string, required): 7-character hex color code with leading # (e.g., #ff0000)

#### `update_label`
Update an existing label.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `labelId` (number, required): Label ID
- `name` (string, optional): Label name
- `color` (string, optional): 7-character hex color code with leading # (e.g., #ff0000)

#### `delete_label`
Delete a label from a repository.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `labelId` (number, required): Label ID

#### `list_issue_labels`
List all labels on a specific issue.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `number` (number, required): Issue number

#### `add_issue_labels`
Add labels to an issue.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `number` (number, required): Issue number
- `labels` (array of numbers, required): Array of label IDs to add

#### `remove_issue_label`
Remove a specific label from an issue.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `number` (number, required): Issue number
- `labelId` (number, required): Label ID to remove

#### `replace_issue_labels`
Replace all labels on an issue with a new set.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `number` (number, required): Issue number
- `labels` (array of numbers, required): Array of label IDs to set (replaces all existing labels)

#### `remove_all_issue_labels`
Remove all labels from an issue.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `number` (number, required): Issue number

### Organization Management Tools

#### `list_user_organizations`
List organizations for the authenticated user.
- No parameters required

#### `create_organization`
Create a new organization.
- `username` (string, required): Organization username (alphanumeric, dashes, underscores)
- `full_name` (string, optional): Organization full name
- `description` (string, optional): Organization description
- `website` (string, optional): Organization website
- `location` (string, optional): Organization location

#### `list_public_organizations`
List public organizations for a specific user.
- `username` (string, required): Username to get public organizations for

#### `get_organization`
Get information about a specific organization.
- `orgname` (string, required): Organization name

#### `update_organization`
Update an organization (requires owner permissions).
- `orgname` (string, required): Organization name
- `full_name` (string, optional): Organization full name
- `description` (string, optional): Organization description
- `website` (string, optional): Organization website
- `location` (string, optional): Organization location

#### `add_organization_member`
Add or update organization membership (requires owner permissions).
- `orgname` (string, required): Organization name
- `username` (string, required): Username to add as member
- `role` (string, required): Member role - 'admin' or 'member'

### Team Management Tools

#### `list_organization_teams`
List teams in an organization.
- `orgname` (string, required): Organization name

#### `create_team`
Create a new team in an organization (requires admin permissions).
- `orgname` (string, required): Organization name
- `name` (string, required): Team name (max 30 characters, alphanumeric with dashes and dots)
- `description` (string, optional): Team description (max 255 characters)
- `permission` (string, optional): Team permission level - 'read', 'write', or 'admin' (default: 'read')

#### `get_team`
Get information about a specific team.
- `teamId` (number, required): Team ID

#### `add_team_member`
Add a user to a team (requires admin permissions).
- `teamId` (number, required): Team ID
- `username` (string, required): Username to add to the team

#### `remove_team_member`
Remove a user from a team (requires admin permissions).
- `teamId` (number, required): Team ID
- `username` (string, required): Username to remove from the team

### Release Management Tools

#### `list_releases`
List all releases for a repository. Returns release information including tag name, name, description, author, timestamps, and downloadable assets (attachments).
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name

**Note**: Currently only read-only access to releases is supported. Create, update, and delete operations are not available in the Gogs API v1.

## Documented but Not Yet Implemented API Endpoints

The following Gogs API v1 endpoints are officially documented but not yet implemented in this MCP server. These represent potential features for future development:

| Category | Endpoint | Method | Description | Documentation |
|----------|----------|--------|-------------|---------------|
| **User Administration** | `/admin/users` | POST | Create a new user | [Link](https://github.com/gogs/docs-api/blob/master/Administration/Users.md#create-a-new-user) |
| **User Administration** | `/admin/users/:username` | PATCH | Edit an existing user | [Link](https://github.com/gogs/docs-api/blob/master/Administration/Users.md#edit-an-existing-user) |
| **User Administration** | `/admin/users/:username` | DELETE | Delete a user | [Link](https://github.com/gogs/docs-api/blob/master/Administration/Users.md#delete-a-user) |
| **User Administration** | `/admin/users/:username/keys` | POST | Create public key for user | [Link](https://github.com/gogs/docs-api/blob/master/Administration/Users.md#create-a-public-key-for-user) |
| **Repository Administration** | `/admin/users/:username/repos` | POST | Create repository for user/org | [Link](https://github.com/gogs/docs-api/blob/master/Administration/Repositories.md) |
| **Team Administration** | `/admin/teams/:teamid/members` | GET | List all members of a team | [Link](https://github.com/gogs/docs-api/blob/master/Administration/Teams.md#list-all-members-of-a-team) |
| **Team Administration** | `/admin/teams/:teamid/repos/:reponame` | PUT | Add or update team repository | [Link](https://github.com/gogs/docs-api/blob/master/Administration/Teams.md#add-or-update-team-repository) |
| **Team Administration** | `/admin/teams/:teamid/repos/:reponame` | DELETE | Remove team repository | [Link](https://github.com/gogs/docs-api/blob/master/Administration/Teams.md#remove-team-repository) |
| **Public Keys** | `/users/:username/keys` | GET | List public keys for a user | [Link](https://github.com/gogs/docs-api/blob/master/Users/Public%20Keys.md) |
| **Public Keys** | `/user/keys` | GET | List your public keys | [Link](https://github.com/gogs/docs-api/blob/master/Users/Public%20Keys.md) |
| **Public Keys** | `/user/keys/:id` | GET | Get a single public key | [Link](https://github.com/gogs/docs-api/blob/master/Users/Public%20Keys.md) |
| **Public Keys** | `/user/keys` | POST | Create a public key | [Link](https://github.com/gogs/docs-api/blob/master/Users/Public%20Keys.md) |
| **Public Keys** | `/user/keys/:id` | DELETE | Delete a public key | [Link](https://github.com/gogs/docs-api/blob/master/Users/Public%20Keys.md) |
| **Deploy Keys** | `/repos/:username/:reponame/keys` | GET | List deploy keys | [Link](https://github.com/gogs/docs-api/blob/master/Repositories/Deploy%20Keys.md) |
| **Deploy Keys** | `/repos/:username/:reponame/keys/:id` | GET | Get a deploy key | [Link](https://github.com/gogs/docs-api/blob/master/Repositories/Deploy%20Keys.md) |
| **Deploy Keys** | `/repos/:username/:reponame/keys` | POST | Add a new deploy key | [Link](https://github.com/gogs/docs-api/blob/master/Repositories/Deploy%20Keys.md) |
| **Deploy Keys** | `/repos/:username/:reponame/keys/:id` | DELETE | Remove a deploy key | [Link](https://github.com/gogs/docs-api/blob/master/Repositories/Deploy%20Keys.md) |
| **Webhooks** | `/repos/:username/:reponame/hooks` | GET | List hooks | [Link](https://github.com/gogs/docs-api/blob/master/Repositories/Webhooks.md) |
| **Webhooks** | `/repos/:username/:reponame/hooks` | POST | Create a hook | [Link](https://github.com/gogs/docs-api/blob/master/Repositories/Webhooks.md) |
| **Webhooks** | `/repos/:username/:reponame/hooks/:id` | PATCH | Edit a hook | [Link](https://github.com/gogs/docs-api/blob/master/Repositories/Webhooks.md) |
| **Webhooks** | `/repos/:username/:reponame/hooks/:id` | DELETE | Delete a hook | [Link](https://github.com/gogs/docs-api/blob/master/Repositories/Webhooks.md) |
| **Collaborators** | `/repos/:username/:reponame/collaborators` | GET | Get collaborators | [Link](https://github.com/gogs/docs-api/blob/master/Repositories/Collaborators.md) |
| **Collaborators** | `/repos/:username/:reponame/collaborators/:collaborator` | PUT | Add user as a collaborator | [Link](https://github.com/gogs/docs-api/blob/master/Repositories/Collaborators.md) |
| **Collaborators** | `/repos/:username/:reponame/collaborators/:collaborator` | DELETE | Delete collaborator | [Link](https://github.com/gogs/docs-api/blob/master/Repositories/Collaborators.md) |

### Contributing New Endpoints

If you'd like to help implement any of these endpoints:

1. Check the official [Gogs API documentation](https://github.com/gogs/docs-api) for endpoint details
2. Add the method to `src/gogs-client.ts` with proper TypeScript types
3. Add the Zod schema and tool definition to `src/server.ts`
4. Test the endpoint against a real Gogs instance
5. Update this README with the new tool documentation
6. Submit a pull request

## Development

### Run in Development Mode

```bash
npm run dev
```

### Build

```bash
npm run build
```

### Watch Mode

```bash
npm run watch
```

## API Documentation

The Gogs API documentation is included in the `docs-api` submodule. For more information about the Gogs REST API, see:
- [Gogs API Documentation](https://github.com/gogs/docs-api)
- Local docs: `docs-api/README.md`

## Security Considerations

- **Access Tokens**: Keep your access tokens secure. Never commit them to version control.
- **Permissions**: The access token's permissions determine what operations are available.
- **Private Repositories**: Access to private repositories requires authentication.
- **Rate Limiting**: Be aware of any rate limiting imposed by your Gogs server.

## Troubleshooting

### "GOGS_SERVER_URL environment variable is required"
Make sure you've set the `GOGS_SERVER_URL` environment variable or included it in your MCP client configuration.

### "404 Not Found" errors
This can indicate:
- Invalid server URL
- Repository or user doesn't exist
- Authentication required but not provided
- Insufficient permissions

### "401 Unauthorized" errors
- Check that your access token is correct and hasn't expired
- Verify the token has appropriate permissions for the operation

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Acknowledgments

- Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol)
- Designed for [Gogs](https://gogs.io) git hosting
- API documentation from [gogs/docs-api](https://github.com/gogs/docs-api)