Optional OAuth authorization is disabled by default. Read the upgrade and rollback notes before enabling it. For Claude/OpenAI connection failures, see edge troubleshooting.
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), or opt into Forgejo OAuth credential linking. Forgejo OAuth does not provide fine-grained API scopes; scoped PATs remain the narrower option. Administrators decide which MCP tools are enabled globally and available to each user; users choose grants for their MCP tokens.
v0.1.0 is the initial open-source release and supports Forgejo 16.0.2. The v0.2.0 release line and current
mainsupport Forgejo 16.0.3 and include deployment security changes. Review the compatibility matrix, upgrade guide and known limitations before production use.
- 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 or opt-in Forgejo OAuth.
- AES-256-GCM encryption for stored Forgejo access/refresh credentials and show-once MCP tokens.
- A web Dashboard for Forgejo configuration, users, permissions and audit records.
- Admin-configured Forgejo OAuth Client ID, encrypted Client Secret and public base URL, with a fixed, copyable redirect URL and immediate application without a restart.
- Redacted invocation auditing, structured logs, health endpoints and Prometheus metrics.
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 MCP tool policy, Forgejo repository permissions and server-side input limits (plus PAT scopes when using a scoped PAT).
- 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.
MCP client ──Bearer token──> Forgejo MCP /mcp ──user PAT/OAuth──> 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 credential. Forgejo OAuth linking and MCP OAuth client authorization are separate flows.
- An existing Forgejo 16.0.3 instance compatible with the locked API contract for the current
mainbranch - 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.
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/.envBefore 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 -dVerify that the service is ready:
docker compose --env-file deploy/.env -f deploy/compose.yaml ps
curl http://127.0.0.1:8000/health/readyOpen http://127.0.0.1:8000 and sign in with:
- Username:
admin(orFMCP_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.
After signing in:
- Change the bootstrap administrator password.
- Configure and verify the Forgejo base URL.
- Enable the required tools globally.
- Create a user with their expected Forgejo username and send a one-time invitation.
- Set the user's tool allowance.
- Have the user verify a scoped PAT or link their Forgejo account with OAuth.
- Create a static MCP token with explicit tool grants, or complete MCP OAuth consent with a duration and selected tools.
- Connect an MCP client to
POST /mcp.
See the administrator guide and user guide for the complete workflow.
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.
| Need | Document |
|---|---|
| Install and start the service | Getting started |
| Configure Forgejo, users and permissions | Administrator guide |
| Create a PAT and MCP token | User guide |
| Configure Forgejo OAuth and understand permission limits | Forgejo OAuth guide |
| Enable MCP-client OAuth and manage its lifecycle | MCP OAuth operations |
| Connect an MCP client | MCP client configuration |
| Check MCP and Forgejo version support | Version compatibility |
| Review current constraints | Known limitations |
| Inspect tool inputs and behavior | v1 tool catalog |
| Review credential handling | Credential security |
| Review Forgejo 16.0.3 evidence | Forgejo 16.0.3 compatibility report |
Run the disposable full-stack App/PostgreSQL/Forgejo E2E test:
./scripts/test-full-docker-e2e.shThe 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.shRun 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 frontendForgejo defaults to codeberg.org/forgejo/forgejo:16.0.3-rootless. The test Forgejo image uses the official primary registry by default. The runner separately uses data.forgejo.org/forgejo/runner:13, as documented by Forgejo; it is not assumed to exist on Codeberg. If the Forgejo primary registry is unavailable, explicitly select its official mirror without changing image versions:
FORGEJO_IMAGE_REGISTRY=data.forgejo.org ./scripts/test-full-docker-e2e.shFORGEJO_RUNNER_IMAGE_REGISTRY independently overrides the runner registry (default: data.forgejo.org).
FORGEJO_IMAGE overrides the complete Forgejo image reference and takes precedence over the registry setting. 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.jsonLaunch the supported release and comparison baseline to reproduce the complete Swagger comparison with:
./scripts/test-forgejo-openapi-compatibility.shThe integration and full-stack suites negotiate MCP Streamable HTTP protocol version 2025-06-18 explicitly.
Copyright holders license this project under the Apache License 2.0.