Purpose
forgejo-mcp is a Model Context Protocol (MCP) server that connects AI assistants (such as Claude, Gemini, Copilot) with Gitea/Forgejo code repositories, letting AI help you manage repositories.
Main Capabilities
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
Version and Release Management
- Manage releases
- Manage release attachments
Other
- View Pull Requests
- Manage Wiki pages
- View Forgejo/Gitea Actions tasks
Usage
Three installation methods are supported:
- Use Docker (recommended). STDIO mode can skip this step and be configured directly; SSE/Streamable HTTP mode requires running forgejo-mcp as a server first, then configuring the MCP client.
- Install from source.
- Download precompiled binaries (download the version for the corresponding operating system from the Releases page).
The tool provides two main operating modes: stdio (for local integration) and http (for remote access).
Before configuring the MCP client, you need to create an access token on the Forgejo/Gitea server: log in to the instance → Settings → Applications → Access Tokens → Generate New Token → select permission scopes (it is recommended to include at least repository and issue write permissions) → copy the token.
Stdio Mode (local client)
Suitable for integration with local AI assistant clients such as Claude Desktop and Gemini CLI, communicating directly through standard input/output.
HTTP Server Mode (remote access)
Starts a web server, allowing remote clients to connect via HTTP.
- Single-user mode: provide --token (or the environment variable FORGEJOMCP_TOKEN) at startup, and all operations use that token. Example command: forgejo-mcp http --address :8080 --server https://git.example.com --token your_token
- Multi-user mode: when no token is provided, the server requires the client to send an Authorization: Bearer <token> header with each request.
Remote MCP clients can be configured to connect to a multi-user mode server; if connecting to a single-user mode server, the headers field can be omitted.
Security Recommendations
- Use environment variables: set FORGEJOMCP_SERVER and FORGEJOMCP_TOKEN, then remove --server and --token from the configuration.
- Limit token permissions: grant only the necessary permission scopes.
- Rotate tokens regularly: update access tokens periodically.
Use Cases
- Intelligent progress tracking: let AI help track project progress and analyze bottlenecks.
- Automated issue classification: automatically label issues and set milestones based on content.
- Priority sorting: let AI analyze issue content to help determine task priorities.
- Code review assistance: get AI suggestions and insights in Pull Requests.
- Project documentation organization: automatically organize Wiki documents and release notes.
Limitations and Support
The project uses the Mozilla Public License 2.0. Bug reports can be submitted via GitHub Issues, and code contributions via Pull Requests are welcome. Specific details on the token permissions used, the complete list of environment variables, and detailed steps for each installation method are not fully provided in this material by the official documentation.
