gogs-mcp

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

• Milestone Management

  • List all milestones in a repository
  • Get specific milestone details
  • Create new milestones
  • Update existing milestones
  • Delete milestones

• 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:

   git clone ssh://git@207.154.220.231:10022/claude/gogs-mcp.git
   cd gogs-mcp
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Docker Setup

1. Clone this repository:

   git clone ssh://git@207.154.220.231:10022/claude/gogs-mcp.git
   cd gogs-mcp
   

2. Create a .env file from the example:

   cp .env.example .env
   

3. Edit .env and configure your Gogs server URL and access token:

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

4. Build and run with Docker Compose:

   docker-compose up -d
   

Or build the Docker image manually:

   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:

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

{
  "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:

   TRANSPORT_MODE=http
   HTTP_PORT=3000
   HTTP_HOST=0.0.0.0
   

2. Start the server:

   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

# 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:

# 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:

{
  "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:

{
  "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

Milestone Management Tools

list_milestones

List all milestones in a repository.

• owner (string, required): Repository owner username
• repo (string, required): Repository name

get_milestone

Get a specific milestone by ID.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• milestoneId (number, required): Milestone ID

create_milestone

Create a new milestone in a repository.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• title (string, required): Milestone title
• description (string, optional): Milestone description
• due_on (string, optional): Due date in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)

update_milestone

Update an existing milestone.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• milestoneId (number, required): Milestone ID
• title (string, optional): Milestone title
• description (string, optional): Milestone description
• due_on (string, optional): Due date in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)
• state (string, optional): Milestone state - 'open' or 'closed'

delete_milestone

Delete a milestone from a repository.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• milestoneId (number, required): Milestone ID

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.

Collaborator Management Tools

list_collaborators

List all collaborators for a repository. Returns user information including username, full name, email, avatar URL, and their permission levels (admin, push, pull).

• owner (string, required): Repository owner username
• repo (string, required): Repository name

check_collaborator

Check if a user is a collaborator on a repository. Returns a boolean indicating whether the specified user has collaborator access.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• username (string, required): Username to check for collaborator status

add_collaborator

Add a user as a collaborator to a repository with specified permissions.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• username (string, required): Username to add as collaborator
• permission (string, optional): Permission level - 'read', 'write', or 'admin' (default: 'write')

remove_collaborator

Remove a user's collaborator access from a repository.

• owner (string, required): Repository owner username
• repo (string, required): Repository name
• username (string, required): Username to remove as collaborator

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
User Administration	/admin/users/:username	PATCH	Edit an existing user	Link
User Administration	/admin/users/:username	DELETE	Delete a user	Link
User Administration	/admin/users/:username/keys	POST	Create public key for user	Link
Repository Administration	/admin/users/:username/repos	POST	Create repository for user/org	Link
Team Administration	/admin/teams/:teamid/members	GET	List all members of a team	Link
Team Administration	/admin/teams/:teamid/repos/:reponame	PUT	Add or update team repository	Link
Team Administration	/admin/teams/:teamid/repos/:reponame	DELETE	Remove team repository	Link
Public Keys	/users/:username/keys	GET	List public keys for a user	Link
Public Keys	/user/keys	GET	List your public keys	Link
Public Keys	/user/keys/:id	GET	Get a single public key	Link
Public Keys	/user/keys	POST	Create a public key	Link
Public Keys	/user/keys/:id	DELETE	Delete a public key	Link
Deploy Keys	/repos/:username/:reponame/keys	GET	List deploy keys	Link
Deploy Keys	/repos/:username/:reponame/keys/:id	GET	Get a deploy key	Link
Deploy Keys	/repos/:username/:reponame/keys	POST	Add a new deploy key	Link
Deploy Keys	/repos/:username/:reponame/keys/:id	DELETE	Remove a deploy key	Link
Webhooks	/repos/:username/:reponame/hooks	GET	List hooks	Link
Webhooks	/repos/:username/:reponame/hooks	POST	Create a hook	Link
Webhooks	/repos/:username/:reponame/hooks/:id	PATCH	Edit a hook	Link
Webhooks	/repos/:username/:reponame/hooks/:id	DELETE	Delete a hook	Link

Contributing New Endpoints

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

1. Check the official Gogs API documentation 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

npm run dev

Build

npm run build

Watch Mode

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
• 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
• Designed for Gogs git hosting
• API documentation from gogs/docs-api