π€ AI-Generated Content β The content of this repository, including all source code, documentation, and configuration files, has been generated by an artificial intelligence assistant or created using artificial intelligence assistant. While efforts have been made to ensure correctness and security, the code should be reviewed before use in any production environment.
mcp-forgejo β MCP Server

Badge note: the Go Reference badge above links to
https://pkg.go.dev/github.com/teran/mcp-forgejo (module path
github.com/teran/mcp-forgejo). The Test Coverage, gosec,
govulncheck and gremlins badges are placeholders wired to the CI
source β the checks they represent are enforced in .github/workflows/ci.yml
(the coverage gate requires β₯ 95%, gosec/govulncheck findings are
fixed-not-suppressed, and gremlins runs as a hard mutation-testing gate).
A Model Context Protocol server that wraps the
Forgejo REST API so a model-driven client can perform common
software-development tasks: repositories, files, issues, pull requests,
branches, releases, and organizations.
Default language for this repository is English. SPEC.md and AGENTS.md
are strictly English. If you need the README (or any doc) in another language,
you must request it explicitly.
Features
The server exposes 51 tools covering the full read β write/update β delete
surface. Each is a complete use-case (no client-side chaining of low-level
calls) and is described with full metadata (annotations + per-tool instructions)
in SPEC.md Β§6.
Read (19)
forgejo_repo_search β search repositories
forgejo_repo_get β repository details
forgejo_repo_list_contents β list directory contents
forgejo_file_get β read a file
forgejo_diff_get β diff between refs, or a PR diff
forgejo_commit_list β list commits
forgejo_branch_list β list branches
forgejo_branch_get β get a branch
forgejo_org_list β list your organizations
forgejo_issue_list β list issues
forgejo_issue_get β get an issue and its comments
forgejo_pull_list β list pull requests
forgejo_pull_get β get a PR with its changed files and checks
forgejo_release_list β list releases (or the latest)
forgejo_tag_list β list tags
forgejo_milestone_list β list milestones
forgejo_label_list β list labels
forgejo_user_get β get the current user, or a user by name
forgejo_user_list β search users
Write / Update (22)
forgejo_repo_create β create a repository (current user or an org)
forgejo_repo_update β update a repository
forgejo_repo_fork β fork a repository
forgejo_org_create β create an organization
forgejo_file_write β write or update a file in one commit
forgejo_file_write_many β write several files in one commit
forgejo_branch_create β create a branch
forgejo_issue_create β create an issue
forgejo_issue_update β update / close / reopen an issue
forgejo_issue_comment_add β add an issue comment
forgejo_issue_set_labels β replace the labels of an issue
forgejo_pull_create β create a pull request
forgejo_pull_update β update / close / reopen a PR
forgejo_pull_merge β merge a PR (merge/squash/rebase)
forgejo_pull_review β create and submit a PR review
forgejo_release_create β create a release
forgejo_release_asset_upload β upload a release asset
forgejo_tag_create β create a tag
forgejo_milestone_create β create a milestone
forgejo_milestone_update β update a milestone
forgejo_label_create β create a label
forgejo_label_update β update a label
Delete (10) β destructive; these require explicit confirmation
forgejo_file_delete β delete a file
forgejo_branch_delete β delete a branch (never the default branch)
forgejo_issue_delete β delete an issue
forgejo_comment_delete β delete an issue comment
forgejo_release_delete β delete a release
forgejo_repo_delete β delete a repository
forgejo_org_delete β delete an organization
forgejo_tag_delete β delete a tag
forgejo_milestone_delete β delete a milestone
forgejo_label_delete β delete a label
Requirements
- Go 1.27+ (see
go.mod / GO_VERSION in CI).
Install & Run
go build -o mcp-forgejo ./cmd/mcp-forgejo
Run locally (stdio)
FORGEJO_URL=https://git.example.com FORGEJO_TOKEN=<pat> \
./mcp-forgejo -mode stdio
Run as a remote sidecar (HTTP/SSE)
FORGEJO_URL=https://git.example.com FORGEJO_TOKEN=<pat> \
LISTEN_ADDR=:8080 ./mcp-forgejo -mode http
Or run the container image (built by GoReleaser β the Dockerfile only
copies the prebuilt binary in, it does not recompile; see Dockerfile):
goreleaser build --snapshot --clean --single-target --output dist/mcp-forgejo
docker build -t mcp-forgejo .
docker run --rm -p 8080:8080 \
-e FORGEJO_URL=https://git.example.com \
-e FORGEJO_TOKEN=<pat> \
mcp-forgejo -mode http
Example: STDIO
Minimal configuration β the server reads FORGEJO_URL and FORGEJO_TOKEN from
the environment and talks to the local client over stdin/stdout:
export FORGEJO_URL=https://git.example.com
export FORGEJO_TOKEN=<pat>
# Optional:
export LOG_LEVEL=info # enable logging (writes to /tmp/mcp-forgejo.log, chmod 600)
export LOG_FILENAME=/tmp/mcp-forgejo.log
export LOG_FORMAT=text # or "json"
./mcp-forgejo -mode stdio
The -mode flag may be omitted β stdio is the default when neither
-mode nor -mode http is given.
Example: HTTP/SSE
The same env vars plus the listener address. Logs go to stdout
(12-factor), so this mode is meant to run as a sidecar behind a reverse proxy
that terminates TLS and enforces client auth:
export FORGEJO_URL=https://git.example.com
export FORGEJO_TOKEN=<pat>
export LISTEN_ADDR=:8080
export LOG_LEVEL=info # optional in HTTP mode β defaults to "info" (to stdout)
export LOG_FORMAT=text # or "json"
./mcp-forgejo -mode http
The client connects to the MCP streamable HTTP endpoint served at the
listener root (the SDK's StreamableHTTPHandler, see server/http.go);
the path is configurable in the SDK options.
Configuration (env vars)
| Env var |
Type |
Default |
Description |
FORGEJO_URL |
string |
(from env) |
Base URL of the Forgejo instance, e.g. https://git.example.com. Required. |
FORGEJO_TOKEN |
string |
(empty) |
Forgejo personal access token (PAT). Secret β never logged/leaked. Required for the stdio transport; optional for the HTTP transport (over HTTP the token is supplied per-request via Authorization: Bearer <token>; FORGEJO_TOKEN is only a fallback). |
LISTEN_ADDR |
string |
:8080 |
MCP listen address for the HTTP/SSE MCP transport (O04). |
INTERNAL_ADDR |
string |
:8081 |
Internal observability address β separate listener for /metrics, /debug/pprof/*, /healthz, /readyz (HTTP/SSE mode only; see Metrics & Observability). |
LOG_LEVEL |
string |
(unset) |
Logging level (trace/debug/info/warn/error). Transport-dependent (L02): in HTTP/SSE mode logging is always enabled, defaulting to info when LOG_LEVEL is unset; in stdio mode it is enabled only when set β unset β disabled (no log file). |
LOG_FILENAME |
string |
/tmp/mcp-forgejo.log |
Log file path for stdio transport (chmod 600). Ignored for HTTP/SSE (logs go to stdout, 12-factor). |
LOG_FORMAT |
string |
text |
text (logrus text, full absolute timestamp) or json. |
Configuration is loaded with
kelseyhightower/envconfig.
There is no ALLOW_DIRS: the server never touches the local filesystem β
all operations go to the remote Forgejo API (see SPEC.md Β§3).
Startup banner
When logging is enabled β always in HTTP/SSE mode (defaults to info); in
stdio mode only when LOG_LEVEL is set β the server writes a
startup banner as the first log line on the transport's logging channel
(file for stdio, stdout for HTTP/SSE):
Starting mcp-forgejo/1.2.3 (commit: abc1234; built at 2026-09-10T12:00:00Z)
The banner is populated at build time via ldflags
(appName/appVersion/appCommitHash/appTimestamp, see .goreleaser.yaml
and SPEC.md Β§8 B02/B05).
Metrics & Observability
In HTTP/SSE mode the server exposes an observability endpoint on a separate
internal listener, INTERNAL_ADDR (default :8081), distinct from the MCP
listen address (LISTEN_ADDR, default :8080). It is always enabled in
HTTP/SSE mode β there is no opt-out β and is not started in stdio mode. A reverse
proxy should forward only the MCP listener, never the observability one.
| Endpoint |
Purpose |
GET /metrics |
Prometheus metrics via the promhttp default registry β the standard Go collectors (runtime/memstats + net/http) plus upstream Forgejo response metrics (O03): forgejo_upstream_request_duration_seconds, forgejo_upstream_request_total (labelled {method,status}), forgejo_upstream_request_size_bytes, forgejo_upstream_response_size_bytes. |
GET /debug/pprof/β¦ |
net/http/pprof profiling (cmdline, profile, symbol, trace). |
GET /healthz |
Liveness probe (always 200). |
GET /readyz |
Readiness probe (always 200). |
These are served by their own http.Server, separate from the MCP JSON-RPC/SSE
flow. Alongside the standard Go collectors, the upstream Forgejo response metrics
(O03) are exposed on /metrics, observed once per outbound Forgejo request by the
infrastructure client. See SPEC.md Β§7.1.
Transports & Auth
- Transport: Hybrid β STDIO (local editor/CLI companion) and
HTTP/SSE (remote sidecar). See
SPEC.md Β§1 for the task-derived
justification.
- OAuth2: not used β a single Forgejo PAT via
Authorization: token <PAT> is the natural, minimal mechanism. See
SPEC.md Β§2 for the justification.
- TLS: never implemented inside the server. Terminate TLS at the reverse
proxy (nginx / Caddy / ingress) in front of the HTTP/SSE listener.
- HTTP/SSE security: the server authenticates every incoming request with an
Authorization: Bearer <token> header (rejecting others with 401) and uses
that token (or the FORGEJO_TOKEN fallback) against Forgejo. For defense in
depth, place the HTTP/SSE listener behind a reverse proxy that enforces client
authn/authz (mTLS / OIDC / ACL), and prefer a dedicated low-privilege Forgejo
user for the token. See SPEC.md Β§5 (S07).
Token: per-transport handling
The Forgejo PAT is sourced per-transport β the HTTP transport accepts it from the
client, the stdio transport from the environment:
| Role |
When |
How |
| Obtain (HTTP) |
Per incoming HTTP request |
The MCP client sends the PAT as an Authorization: Bearer <token> header. The server reads it, injects it into the request context, and rejects requests lacking a valid Bearer token with 401 Unauthorized. |
| Obtain (stdio) |
Startup / configuration |
The server reads the PAT from the FORGEJO_TOKEN environment variable (required for stdio; startup fails if empty). |
| Present (outbound) |
Every outbound request to Forgejo |
The server sends the resolved token as an Authorization: token <PAT> header on every call it makes to the Forgejo REST API (see forgejo.go). A per-request Bearer token overrides the config fallback. |
Two important clarifications:
- Inbound (HTTP/SSE): the server does authenticate incoming requests β
each request must carry an
Authorization: Bearer <token> header (case-
insensitive scheme, non-empty token) or it is rejected with 401. The Bearer
header on the MCP listener is distinct from the outbound token scheme
used to call Forgejo. For defense in depth, still place the HTTP/SSE listener
behind a reverse proxy that enforces client authn/authz (mTLS / OIDC / ACL).
- Not OAuth2: the Bearer header is a transport wrapper; Forgejo's PAT
mechanism remains the
token scheme (Authorization: token <PAT>). The token
is never logged, leaked in error messages, or echoed in tool outputs (it is
redacted to [REDACTED]).
Development
golangci-lint run ./... # lint + gofmt/gofumpt; findings fixed
go test -race ./... # unit tests with race detector
go-arch-lint check # dependency rules, see .go-arch-lint.yml
gosec ./... # findings must be FIXED
govulncheck ./... # findings must be FIXED
go test -coverprofile=cover.out ./...
go tool cover -func=cover.out | awk '/^total:/ {print $3}' # must be >= 95%
gremlins unleash . --threshold-efficacy=90 --threshold-mcover=80 --timeout-coefficient=60 # HARD GATE
make e2e # e2e tests (needs Docker); also: make e2e-cover
CI enforces a 95% coverage gate (build fails below it), the race detector,
lint, gosec, govulncheck, go-arch-lint, and gremlins (mutation testing) as
a hard gate. See .github/workflows/ci.yml.
End-to-end tests (e2e)
The e2e/ suite verifies the full path between the MCP tool handler and a real
Forgejo backend. It runs through the
github.com/teran/go-docker-testsuite
harness, which spins up a real Forgejo container (requires a Docker daemon):
make e2e # go test -tags e2e ./...
make e2e-cover # e2e with a separate coverage profile (e2e-cover.out)
Every file in e2e/ carries a //go:build e2e build tag, so the suite is
excluded from the default unit run (go test ./... / make test). CI runs it
in a dedicated e2e job as a hard gate (a failing e2e test breaks the build).
See SPEC.md Β§8 (T02/C04/N30).
Architecture
See SPEC.md for the application-level architecture: package layout
(cmd/ + top-level packages), the tool registry, transport wiring, config, security,
logging, and error handling.
Contributing / TDD
This project is developed test-first (TDD): a failing test is written
before the implementation that satisfies it. CI enforces the discipline with a
95% coverage gate and gremlins mutation testing as a hard gate.
The @qa / @developer split referenced elsewhere is how AI agents in
this repo cooperate (each writes tests / implementation in an isolated
context) β see AGENTS.md for the agent operating rules. It does not apply
to a human making changes directly; the test-first rule is universal:
- Write a failing test for the behavior you're adding (new tool, bug fix,
refactor).
- Implement just enough to make it pass.
- Keep the gates green β run the checks in Development
and ensure coverage stays β₯ 95%.
License
Apache License 2.0