forgejo

Forgejo MCP Server acts as an integration layer that lets AI assistants manage your Forgejo/Gitea repositories through natural language. It exposes a remote MCP endpoint that your AI tools can connect to (via stdio or HTTP) to perform operations like creating and labeling issues, managing milestones and labels, browsing repositories, handling pull requests, and organizing wiki pages and release notes. With this setup, AI assistants can analyze project data, suggest actions, and execute repository management tasks in a conversational or command-driven manner. The server supports both single-user mode (token-based) and multi-user mode (per-request Authorization headers) for flexible access control.

To use it, run the Forgejo MCP server (typically via Docker as shown in the installation guide), then configure your MCP client to point at the server and provide the appropriate token or authorization headers. When connected, you can issue natural language requests like creating a new issue with specific labels, generating a release note, or requesting a summary of open milestones. The client translates your query into MCP commands that the Forgejo MCP server executes against your Forgejo/Gitea instance.

Prerequisites:

• Docker installed on the host (recommended method)
• A running Forgejo/Gitea instance accessible from the MCP server
• An access token with appropriate scopes on the Forgejo/Gitea server (for single-user mode)

Method 1 — Run via Docker (recommended):

1. Ensure Docker is installed and running.
2. Run the Forgejo MCP container with the HTTP server mode and your Forgejo server URL:

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

3. The MCP server will listen on port 8080. Configure your MCP client to connect to http://<host>:8080.

Method 2 — Install from source (if you prefer building locally):

1. Ensure Go is installed.
2. Build the binary:

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

3. Run the binary in HTTP mode, pointing to your Forgejo/Gitea server:

/path/to/forgejo-mcp http --address :8080 --server https://git.example.com

Method 3 — Download pre-built binaries:

1. Go to the Releases page and download the appropriate binary for your OS.
2. Run in HTTP mode as shown above.

Prerequisites recap:

• Docker or Go toolchain, as per chosen method
• Access to a Forgejo/Gitea instance with a valid token (for single-user) or be prepared to supply per-request tokens (for multi-user mode).

Tips and common considerations:

• For security, prefer using environment variables to store tokens and avoid embedding tokens directly in the MCP configuration where possible.
• In multi-user mode, clients must send an Authorization: Bearer <token> header with each request.
• If you plan to run in HTTP mode behind a reverse proxy, ensure proper TLS termination and that the Forgejo server URL is accessible from the MCP host.
• When using Docker, you can override the server address and token as needed per deployment by adjusting the --server and FORGEJOMCP_TOKEN values.
• Monitor the Forgejo/Gitea permissions requested by the token; grant only the minimum scopes required (repository and issue write permissions are commonly sufficient).
• If you encounter connectivity issues, verify network access between the MCP host and the Forgejo/Gitea instance, and confirm that the token has not expired or been revoked.