forgejo-mcp

README

Gitea/Forgejo MCP Server

Turn AI into your code repository management assistant

A Model Context Protocol (MCP) server that enables you to manage Gitea/Forgejo repositories through AI assistants like Claude, Gemini, and Copilot.

🚀 Why Use Forgejo MCP Server?

If you want to:

• Smart progress tracking: Let AI help you track project progress and analyze bottlenecks
• Automated issue categorization: Automatically tag issue labels and set milestones based on content
• Priority sorting: Let AI analyze issue content to help prioritize tasks
• Code review assistance: Get AI suggestions and insights in Pull Requests
• Project documentation organization: Automatically organize Wiki documents and release notes

Then this tool is made for you!

✨ Supported 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)
• Repository search and listing

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 Usage section.

For SSE/Streamable HTTP mode, you should run forgejo-mcp as 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 provides two primary modes of operation: stdio for local integration and http for remote access.

Before actually setup you MCP client, you have to create an access token on the Forgejo/Gitea server.

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

💡 Tip: For security, consider setting environment variables instead of using tokens directly in config:

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

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 might want to take a look at Security Recommendations section for best practice.

HTTP Server Mode (for Remote Access)

This mode starts a web server, allowing remote clients to connect via HTTP. It's ideal 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 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 different path in 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! 🚀