forgejo

Forgejo MCP Server connects your Forgejo instance to MCP-compatible AI assistants, enabling natural language control over repositories, issues, pull requests, files, and more. Once configured, you can issue commands like listing your repositories, creating issues, or fetching file contents using any MCP-enabled assistant (for example Claude, Cursor, or a VS Code extension). The server exposes a rich set of tools grouped by domain (User, Repositories, Branches, Files, Commits, Issues, Pull Requests, Actions, Organizations, and Server) that you can invoke from your assistant or via CLI mode. To use the standard setup, connect through stdio transport from your MCP client and provide the Forgejo instance URL and a personal access token. For HTTP-based streaming, you can switch to SSE mode and point the server’s URL accordingly. The tools will return structured results that you can render in your UI or use as input for follow-up questions.

Prerequisites:

• Go compiler and toolchain installed (for Option A).
• A Forgejo instance and a personal access token with the required permissions.
• Optional: a pre-built binary if you prefer not to compile.

Option A — Build from source (Go, Recommended):

1. Clone the repository and navigate into it: git clone https://codeberg.org/goern/forgejo-mcp.git cd forgejo-mcp
2. Install the program: go install .
3. Ensure your GOPATH/bin (typically ~/go/bin) is in your PATH. For example: export PATH="$HOME/go/bin:$PATH"

Note: The known issue states that go install codeberg.org/goern/forgejo-mcp/v2@latest may not work yet. Use the clone-and-build flow shown above.

Option B — Download a binary:

1. Go to the releases page and download the latest release binary.
2. Place the binary somewhere in your PATH, for example /usr/local/bin.

For Arch Linux users (optional):

yay -S forgejo-mcp      # builds from source
yay -S forgejo-mcp-bin  # uses pre-built binary

Configure access tokens and URL in your MCP config as described below.

Tips and common issues:

• Environment variables: Set FORGEJO_URL (or provide --url) and FORGEJO_ACCESS_TOKEN (or --token) as required by your transport mode. In stdio mode, the token is supplied via FORGEJO_ACCESS_TOKEN.
• If you encounter issues with go install, prefer cloning the repository and building locally as shown in the Quick Start.
• In SSE mode, you’ll run the server with transport sse and provide the URL of your Forgejo instance, then connect your MCP client to the SSE endpoint.
• Debugging: enable debug mode with --debug or FORGEJO_DEBUG to get verbose logs.
• The API surface includes a wide range of tools (e.g., list_my_repos, create_issue, get_file_content). Refer to the Available Tools section in the README for full commands and parameters.
• When using CLI mode, your environment variables for Forgejo URL and token apply as well, and results are written to stdout in JSON by default.