Forgejo / Codeberg / Gitea

forgejo-mcp-rs

A Model Context Protocol server for Forgejo, Codeberg and Gitea. It lets an MCP client (Claude Code, Claude Desktop, …) read your forge — the authenticated user, repositories, issues, and pull requests — over the Forgejo/Gitea REST API.

Status: read-only by default, with opt-in guarded writes (since v0.2). Read tools across

the forge — user, repos, issues, pull requests, search, orgs, notifications, comments,

reviews, and Actions (CI) runs — plus guarded writes (create_repo, edit_repo,

create_branch, delete_branch, create_issue, edit_issue, comment_on_issue,

create_pull_request, create_pull_request_review, merge_pull_request,

create_or_update_file, delete_file, delete_repo, migrate_repo, push-mirror

management, dispatch_workflow, cancel_workflow_run and rerun_workflow) gated behind a separate write token and a deliberate,

time-boxed write mode. See SPECIFICATION.md for the full design.

It speaks the Forgejo REST API directly through a small, in-house client (src/forgejo/client.rs, over the src/mcp_core/ transport) — an independent implementation over the documented API, not a port of any other server. There is no third-party forge SDK in the trust path, so the tool surface holding your token is code you can read and audit end to end.

The server speaks MCP protocol version 2026-07-28 (since v0.16) and negotiates down to 2024-11-05, so older clients keep working unchanged. It runs over stdio and exposes tools only — no resources, prompts, sampling, or roots.

Build

cargo build --release   # target/release/forgejo-mcp-rs

cargo install --path . # install to ~/.cargo/bin

Runs on macOS, where it is developed and used daily, and Linux, where it builds and runs (Glama builds and inspects it on Debian). Windows is untested.

Woodpecker CI

A companion server for Woodpecker CI shipped in this crate as a second woodpecker-mcp binary from v0.13.0 through v0.17.0. It now lives in its own repository and crate: woodpecker-mcp.

Woodpecker is its own system — it drives Gitea, GitHub, GitLab, and Bitbucket as readily as Forgejo, and that server never called the Forgejo API at all — so bundling it here made it invisible to everyone not running Forgejo. Nothing about it changed in the move; if you were using the woodpecker-mcp binary from this crate, install it from the new crate instead and point your MCP client at the new path.

Configure

The server is configured by environment variables:

Mint a token at Codeberg → Settings → Applications (or your instance's equivalent). For the read tools, read scopes (read:repository, read:issue, read:user) suffice. The write token needs write:repository (including delete, and the repo-admin push-mirror endpoints).

A read token is mandatory: the server refuses to start on a write token alone, and the read token must be a *different* token from FORGEJO_TOKEN_WRITE — you can't shortcut by reusing the write token for reads.

Forgejo 15+ token scoping. Forgejo 15.0 tightened authorization on many repository

APIs to match its fine-grained, repository-scoped access tokens. Classic broad tokens are

unaffected, but if you mint a *repository-scoped* token it must actually carry the scopes

above — in particular the repo-admin scope for the push-mirror tools, which otherwise return

403. Scope the token to every repo you intend to reach.

Forgejo and Gitea

Forgejo began as a Gitea fork, and the REST surface is still very nearly the same one. Of the ~25 endpoints this server calls, only the Actions (CI) ones differ. Issues, pull requests, diffs, PR files, branches, file contents, search, orgs, notifications, push mirrors, and migration are identical in path, method, and response shape on both, so they need no special handling and get none.

The flavor is detected once, lazily, from the instance's GET /version — and only the Actions tools ever ask. Set FORGEJO_FLAVOR to forgejo or gitea to pin it if the detection ever guesses wrong on your instance.

The detection reads oddly on purpose: Forgejo names Gitea in its own version string

(Codeberg reports 16.0.0-dev-785-465b60ef+gitea-1.22.0) to advertise API compatibility,

while Gitea never names itself (29.0.0+dev-160-g55186ca39b). So a gitea- marker means

Forgejo, and anything without it is Gitea. The major version is no guide: Gitea has left the

1.x line, and before v0.21.0 that made gitea.com look like Forgejo.

Where the two forges differ, and what the server does about it:

Translating rather than sending both spellings is deliberate: an unknown query parameter is *ignored*, not rejected, so sending Forgejo's ref to Gitea would silently return unfiltered runs — a filter that looks applied but isn't.

Gitea's path deserves its own warning, because the name lies: it is not a filesystem path. It is the workflow file, an @, and the fully-qualified ref — ci.yml@refs/heads/main, or test-pr.yml@refs/pull/1117/head. It is also the only reliable source of the ref, since head_branch is populated for branch runs and null for tags and pull requests.

Two more things regardless of flavor. Gitea requires a token for the Actions API even on public repositories. get_workflow_run answers in the same normalized shape as list_workflow_runs.

Write mode

The server is read-only by default. create_repo / edit_repo / delete_repo work only when (a) FORGEJO_TOKEN_WRITE is configured and (b) you've deliberately entered write mode via enable_write_mode — a time-boxed elevation (default 10 min, max 60) that slides forward on each write and auto-reverts. write_status reports the state; delete_repo also requires a confirm argument equal to "owner/repo".

enable_write_mode, disable_write_mode and write_status all report the instance they apply to, and the elevation note names it in prose, so the announcement reads "write mode is active on https://gitea.com/" rather than a bare "write mode is on". That matters once you run more than one of these servers at once — a Codeberg one and a Gitea one, say — where each has its own independent write mode and an unqualified warning tells you nothing about which forge is now writable. write_status deliberately never calls the instance, so its flavor is null until something else has detected it. See SPECIFICATION.md for the full design.

Migration source token (optional)

Only needed if you'll use migrate_repo against a private source. Public sources need no credential — skip this entirely.

Note the direction: every other variable here authenticates to *your* instance (FORGEJO_URL). FORGEJO_MIGRATE_TOKEN authenticates to a different instance — the one you're copying *from*.

1. Mint a token on the source instance (its Settings → Applications), not on your own.
2. Give it read scopes only — read:repository, plus read:issue if you're migrating issues and PRs. It never needs write: the migration only reads from the source. On Forgejo and Gitea, also set its repository access to all repositories, not public only, or a private source stays out of its reach.
3. Set it as FORGEJO_MIGRATE_TOKEN in the same env block as your other tokens, on the server for the destination instance: that server asks the destination to do the copying, and the destination presents the token to the source.
4. Call migrate_repo with authenticate: true. Without it the token is not sent at all.

**Understand where this token goes