Forgejo MCP

🚀 Gitea/Forgejo MCP Server

Transform AI into your code repository management assistant

A Model Context Protocol (MCP) server that allows you to manage Gitea/Forgejo repositories via AI assistants such as Claude, Gemini, and Copilot.

🚀 Why Use Forgejo MCP Server?

If you aim to:

• Smart progress tracking: Let AI assist you in tracking project progress and analyzing bottlenecks.
• Automated issue categorization: Automatically label issues and set milestones according to their content.
• Priority sorting: Have AI analyze issue content to prioritize tasks.
• Code review assistance: Obtain AI suggestions and insights during Pull Requests.
• Project documentation organization: Automatically organize Wiki documents and release notes.

Then this tool is tailored for you!

✨ Features

Issue Management

• Create, edit, and view issues.
• Add, remove, and replace labels.
• Manage issue comments and attachments.
• Set issue dependencies.

Project Organization

• Manage labels (create, edit, delete).
• Manage milestones (create, edit, delete).
• Search and list repositories.

Release Management

• Manage version releases.
• Manage release attachments.

Other Features

• View Pull Requests.
• Manage Wiki pages.
• View Forgejo/Gitea Actions tasks.

📦 Installation

Method 1: Use Docker (Recommended)

For STDIO mode, you can skip to the Usage section.

For SSE/Streamable HTTP mode, you should run forgejo-mcp as a server before configuring your MCP client.

docker run -p 8080:8080 -e FORGEJOMCP_TOKEN="my-forgejo-api-token" ronmi/forgejo-mcp http --address :8080 --server https://git.example.com

Method 2: Install from Source

go install github.com/raohwork/forgejo-mcp@latest

Method 3: Download Pre-compiled Binaries

Download the appropriate version for your operating system from the Releases page.

💻 Usage

This tool offers two main operation modes: stdio for local integration and http for remote access.

Before setting up your MCP client, you need to create an access token on the Forgejo/Gitea server.

1. Log in to your Forgejo/Gitea instance.
2. Navigate to Settings → Applications → Access Tokens.
3. Click Generate New Token.
4. Select appropriate permission scopes (it is recommended to have at least repository and issue write permissions).
5. Copy the generated token.

💡 Usage Tip

For security, consider setting environment variables instead of using tokens directly in the configuration:

export FORGEJOMCP_SERVER="https://your-forgejo-instance.com"
export FORGEJOMCP_TOKEN="your_access_token"

Basic Usage

Stdio Mode (for Local Clients)

This is the recommended mode for integrating with local AI assistant clients like Claude Desktop or Gemini CLI. It uses standard input/output for direct communication.

Configure Your AI Client

Using Docker:

{
  "mcpServers": {
    "forgejo": {
      "command": "docker",
      "args": [
        "--rm",
        "ronmi/forgejo-mcp",
        "stdio",
        "--server", "https://your-forgejo-instance.com",
        "--token", "your_access_token"
      ]
    }
  }
}

Installed from source or pre-built binary:

{
  "mcpServers": {
    "forgejo": {
      "command": "/path/to/forgejo-mcp",
      "args": [
        "stdio",
        "--server", "https://your-forgejo-instance.com",
        "--token", "your_access_token"
      ]
    }
  }
}

You may refer to the Security Recommendations section for best practices.

Advanced Usage

HTTP Server Mode (for Remote Access)

This mode starts a web server, enabling remote clients to connect via HTTP. It is suitable for web-based services or setting up a central gateway for multiple users.

Run the following command to start the server:

# with local binary
/path/to/forgejo-mcp http --address :8080 --server https://your-forgejo-instance.com

# with docker
docker run -p 8080:8080 -d --rm ronmi/forgejo-mcp http --address :8080 --server https://your-forgejo-instance.com

The server supports two operational modes:

• Single-user mode: If you provide a --token (or the environment variable FORGEJOMCP_TOKEN) at startup, all operations will use that token.

  forgejo-mcp http --address :8080 --server https://git.example.com --token your_token
  

• Multi-user mode: If no token is provided, the server requires clients to send an Authorization: Bearer <token> header with each request, allowing it to serve multiple users securely.

Client Configuration

For clients that support connecting to a remote MCP server via HTTP, you can add a configuration like this. This example shows how to connect to a server running in multi-user mode:

{
  "mcpServers": {
    "forgejo-remote": {
      "type": "sse",
      "url": "http://localhost:8080/sse",
      "headers": {
        "Authorization": "Bearer your_token"
      }
    }
  }
}

or http type (for Streamable HTTP, use a different path in the URL)

{
  "mcpServers": {
    "forgejo-remote": {
      "type": "http",
      "url": "http://localhost:8080/",
      "headers": {
        "Authorization": "Bearer your_token"
      }
    }
  }
}

If connecting to a server in single-user mode, you can omit the headers field.

🔧 Security Recommendations

1. Use environment variables: Set FORGEJOMCP_SERVER and FORGEJOMCP_TOKEN, then remove --server and --token from your configuration.
2. Limit token permissions: Only grant necessary permission scopes.
3. Rotate tokens regularly: Update access tokens periodically.

💻 Usage Examples

After configuration, you can use natural language in your AI assistant to manage your repositories:

"Show me critical bug reports of this repo on my gitea server"

"According to our discussion above, create a detailed issue about this bug, then leave a comment on the issue to describe how we will fix it."

"Give me a report about current milestone. Recent progression in particular."

"Analyze recent pull requests and tell me which ones need priority review"

🤝 Support & Contributing

• Bug Reports: GitHub Issues
• Code Contributions: Pull Requests are welcome!

📄 License

This project is licensed under the Mozilla Public License 2.0.

Start making AI your code repository management partner! 🚀