forgejo-mcp

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
Upload and 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.

Log in to your Forgejo/Gitea instance
Go to Settings → Applications → Access Tokens
Click Generate New Token
Select appropriate permission scopes (recommend at least repository and issue write permissions)
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

Use environment variables: Set FORGEJOMCP_SERVER and FORGEJOMCP_TOKEN, then remove --server and --token from your configuration
Limit token permissions: Only grant necessary permission scopes
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! 🚀

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

An MCP server for managing your repositories on Forgejo/Gitea server.

Related MCP Servers

Gitee
normal-coder
A
security
A
license
A
quality
MCP Tool Server for Gitee, supporting the management of repository files/branches, Issues, and Pull Requests.
Last updated -
20
674
7
TypeScript
MIT License
Git MCP
kjozsa
A
security
F
license
A
quality
MCP server for managing Git operations on local repositories, allowing users to list repositories, get and create tags, list commits, push tags, and refresh repositories through a standardized interface.
Last updated -
6
3
Python
GitLab MCP Server
harshmaur
-
security
A
license
-
quality
An MCP server that enables communication with GitLab repositories, allowing interaction with GitLab's API to manage projects, issues, and repositories through natural language.
Last updated -
3,805
1
JavaScript
MIT License
Git PR MCP Server
peterj
-
security
F
license
-
quality
An MCP server that enables Git repository operations and GitHub PR workflows, allowing users to manage repositories, create branches, commit changes, and create pull requests through natural language.
Last updated -
1
Python

View all related MCP servers