Forgejo MCP

The current main branch requires Forgejo 16.0.3. Forgejo 16.0.2 is retained only as a comparison baseline; see the version compatibility matrix.

Upgrading an existing installation? Read the security upgrade instructions.

繁體中文

Maintainers: versioned Docker image and GitHub Release workflow.

Forgejo MCP is a self-hosted Model Context Protocol server and management Dashboard that gives organizations centrally governed, controlled and observable AI access to an existing Forgejo instance.

Users connect with their own scoped Forgejo personal access tokens (PATs). Administrators decide which MCP tools are enabled globally, available to each user and granted to each show-once MCP token.

v0.1.0 is the initial open-source release and supports Forgejo 16.0.2. The v0.2.0 release line and current main support Forgejo 16.0.3 and include deployment security changes. Review the compatibility matrix, upgrade guide and known limitations before production use.

What it provides

• 50 tools for repositories, organization repository creation, migration and pull-mirror management, git trees, branches, commits, labels, milestones, Issues, pull requests, reviews, Actions runs, jobs, logs and artifacts, tags and releases.

• Global, user and token-level tool authorization in addition to Forgejo's own permissions.

• Per-user Forgejo identity through a verified, scoped PAT.

• AES-256-GCM encryption for stored PATs and show-once MCP tokens.

• A web Dashboard for Forgejo configuration, users, permissions and audit records.

• Redacted invocation auditing, structured logs, health endpoints and Prometheus metrics.

Related MCP server: devflow-mcp

Governance for company use

Forgejo MCP is designed as a governance layer between company AI clients and Forgejo—not merely as another API wrapper.

• Manageable permissions: administrators centrally control which tools are enabled globally, available to each user and granted to each MCP token.

• Controlled operations: AI clients never receive an unrestricted shared Forgejo token. Every operation remains bounded by the user's PAT scopes, Forgejo repository permissions and server-side input limits.

• Traceable identity: each MCP token belongs to a specific user and client, so activity is not hidden behind a shared service account.

• Auditable behavior: tool, user, target, authorization decision, status, duration and correlation identifiers are recorded with sensitive values redacted.

• Observable service: structured logs, health checks, Prometheus metrics and request/user/invocation correlation support operational inspection.

• Revocable access: administrators can revoke one client token, remove selected tool grants, deactivate a Forgejo credential or suspend a user.

• Credential isolation: MCP tokens and Forgejo PATs are separate credentials. An MCP token neither contains nor reveals the PAT; if only an MCP token is exposed, it can be revoked without rotating the Forgejo PAT.

How it works

MCP client ──Bearer token──> Forgejo MCP /mcp ──user PAT──> Forgejo API
                                  │
Web Dashboard ──admin/user──> permissions, credentials and audit records
                                  │
                              PostgreSQL

Forgejo MCP does not replace Forgejo authorization. A tool is available only when it is globally enabled, allowed for the user, granted to the MCP token, and permitted by the user's Forgejo account and PAT.

Requirements

• An existing Forgejo 16.0.3 instance compatible with the locked API contract for the current main branch

• Docker Engine with Docker Compose

• OpenSSL for generating local secrets

The supported v0.1.0 deployment builds the React Dashboard into the App image and starts the App and PostgreSQL together. Operators do not need separate frontend and backend processes.

Quick start

New installations only. For an existing deployment, follow the upgrade guide; do not regenerate its database password or encryption key.

From the repository root:

cp deploy/compose.example.env deploy/.env

Before starting, edit deploy/.env: replace FMCP_FORGEJO_ALLOWED_BASE_URLS with your exact Forgejo base URL, not the git.example.com placeholder. Use FMCP_COOKIE_SECURE=true behind production HTTPS; false is only for direct localhost HTTP. The commands below assume the default POSTGRES_USER and POSTGRES_DB (forgejo_mcp); if changed, use matching values in database_url.

umask 077
mkdir -p deploy/secrets
openssl rand -base64 32 > deploy/secrets/admin_password
openssl rand -base64 32 > deploy/secrets/credential_key
postgres_password="$(openssl rand -hex 32)"
printf '%s\n' "$postgres_password" > deploy/secrets/postgres_password
printf 'postgresql+asyncpg://forgejo_mcp:%s@postgres:5432/forgejo_mcp\n' \
  "$postgres_password" > deploy/secrets/database_url
unset postgres_password
chmod 600 deploy/secrets/admin_password deploy/secrets/credential_key \
  deploy/secrets/postgres_password deploy/secrets/database_url

docker compose --env-file deploy/.env -f deploy/compose.yaml up --build -d

Verify that the service is ready:

docker compose --env-file deploy/.env -f deploy/compose.yaml ps
curl http://127.0.0.1:8000/health/ready

Open http://127.0.0.1:8000 and sign in with:

• Username: admin (or FMCP_BOOTSTRAP_ADMIN_USERNAME)

• Password: the value in deploy/secrets/admin_password

Change the bootstrap password immediately. Direct localhost HTTP requires FMCP_COOKIE_SECURE=false; secure cookies should remain enabled behind HTTPS.

Production startup also requires FMCP_FORGEJO_ALLOWED_BASE_URLS, a JSON list containing the exact trusted Forgejo base URL (for example ["https://git.example.com"]). This out-of-band pin prevents a Dashboard administrator from redirecting user PAT verification to another server. Browser-based MCP clients must add their exact origins to FMCP_MCP_ALLOWED_ORIGINS; regular MCP clients do not send an Origin header.

For logs, shutdown, clean reset, common startup errors and the optional local Forgejo profile, see Getting started.

First-time setup

After signing in:

1. Change the bootstrap administrator password.

2. Configure and verify the Forgejo base URL.

3. Enable the required tools globally.

4. Create a user with their expected Forgejo username and send a one-time invitation.

5. Set the user's tool allowance.

6. Have the user verify a scoped Forgejo PAT and create an MCP token.

7. Grant the required tools to that token.

8. Connect an MCP client to POST /mcp.

See the administrator guide and user guide for the complete workflow.

MCP connection

Forgejo MCP uses authenticated MCP Streamable HTTP:

URL:           https://forgejo-mcp.example/mcp
Transport:     Streamable HTTP
Authorization: Bearer fmcp_...

The MCP token is shown only once. Store it in the client's secret storage; query-string tokens are rejected. See MCP client configuration for the field mapping, connection checks and troubleshooting guidance.

Documentation

Development and verification

Run the disposable full-stack App/PostgreSQL/Forgejo E2E test:

./scripts/test-full-docker-e2e.sh

The default development image is Forgejo 16.0.3. Re-run the same complete E2E against the 16.0.2 compatibility baseline with:

FORGEJO_IMAGE=data.forgejo.org/forgejo/forgejo:16.0.2-rootless ./scripts/test-full-docker-e2e.sh

Run the individual quality checks:

uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest
npm run lint --prefix frontend
npm run typecheck --prefix frontend
npm run build --prefix frontend

Forgejo defaults to the supported official mirror data.forgejo.org/forgejo/forgejo:16.0.3-rootless; the supported 16.0.3 contract and the 16.0.2 comparison baseline both have locked Swagger checksums. Verify either known contract with:

uv run python scripts/verify_forgejo_openapi.py https://forgejo.example/swagger.v1.json

Launch the supported release and comparison baseline to reproduce the complete Swagger comparison with:

./scripts/test-forgejo-openapi-compatibility.sh

The integration and full-stack suites negotiate MCP Streamable HTTP protocol version 2025-06-18 explicitly.

License

Copyright holders license this project under the Apache License 2.0.