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

• 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

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)

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

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