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:

Variable	Required	Default	Meaning
FORGEJO_TOKEN_READ_ONLY	yes	—	Read token (or FORGEJO_TOKEN). Read-only scopes are enough.
FORGEJO_TOKEN_WRITE	no	—	Write/delete-scoped token. Providing it enables the write tools; omit it for a pure read-only server.
FORGEJO_WRITE_MINUTES	no	10	Default write-mode window (minutes, max 60).
FORGEJO_MIRROR_TOKEN	no	—	Credential add_push_mirror sends as the remote's password (e.g. a GitHub PAT). Kept out of the conversation — never passed as a tool argument. Omit if you only use use_ssh=true mirrors.
FORGEJO_MIGRATE_TOKEN	no	—	Credential migrate_repo sends to the source instance it reads from. Also never passed as a tool argument. Kept separate from FORGEJO_MIRROR_TOKEN on purpose — that one authenticates to a push target, so sharing a variable would send a credential to a host it was never issued for. Omit if you only migrate public repos.
FORGEJO_UPLOAD_ROOT	no	—	Directory upload_release_asset may read files from. Uploading is disabled while this is unset — see Release assets.
FORGEJO_UPLOAD_MAX_MB	no	100	Ceiling on one uploaded asset (MiB). The file is read into memory to be sent.
FORGEJO_URL	no	https://codeberg.org	Instance base URL.
FORGEJO_FLAVOR	no	auto	forgejo, gitea, or auto to detect from the instance version. Only the Actions (CI) tools consult it — see Forgejo and Gitea.

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:

	Forgejo	Gitea	Handling
Run filter by git ref	ref, fully qualified	branch, bare name	Translated; refs/heads/main works on both
Run filter by workflow	workflow_id query parameter	a separate …/actions/workflows/{file}/runs path	Translated
Run outcome	status alone	status (phase) plus conclusion	Normalized: conclusion is promoted into status, and also kept verbatim
Run field names	commit_sha, prettyref, index_in_repo, title, created, trigger_event	head_sha, head_branch, run_number, display_title, created_at, event	Normalized to one shape
Workflow file and ref	separate: workflow_id and prettyref	combined into path, as ci.yml@refs/heads/main	Split apart; the ref is shortened (main, v0.16.0) and a pull-request ref kept whole
Unknown workflow filter	empty list	404 workflow "x.yml" not found	Surfaced as-is; the tool description says which is which
workflow_dispatch reply	the created run (return_run_info)	204 No Content	Forgejo's run is passed through; on Gitea the tool returns an acknowledgement and tells the caller to find the run with list_workflow_runs
Workflow directory	.forgejo/workflows, .github/workflows	.gitea/workflows, .github/workflows	Mentioned in the dispatch_workflow tool description
Jobs of a run	bare array; no timestamps or steps	{ jobs, total_count }, with timestamps and steps	Unwrapped and normalized like runs; what Forgejo omits stays absent
Pull-request filter by branch	base, head (Forgejo 16+)	base_branch only	Translated; head is applied here on Gitea, by walking the list. Every answer is checked against both, since a forge ignores a filter it lacks
Cancel and rerun reply	204 No Content	the run (200/201); a job for a job rerun	The run from the reply where there is one, otherwise read back; reported in list_workflow_runs' shape
Rerun one job	…/actions/jobs/{job_id}/rerun	…/actions/runs/{run}/jobs/{job_id}/rerun	Translated; run_id is required on both
Cancel a finished run	204, left unchanged	unverified; its spec lists a 409 Conflict	Errors surfaced as-is; on success the returned run's status says what happened

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 before you set it. Your read/write tokens travel as an Authorization header to FORGEJO_URL and nowhere else. This one is different: it goes in the request body, and your destination instance then presents it to the source host on your behalf. The destination sees it in cleartext. That's inherent to any server-side migration API, not a choice this server makes — but it means you're extending trust to the destination operator. Scope the token to the single repository if your source supports it, and revoke it once the migration lands.

With mirror: true the destination must retain the credential to keep re-fetching, so it will persist in that instance's database rather than being used once and discarded. Prefer a one-shot migration unless you actually want an ongoing pull mirror.

Wire it into Claude Code

claude mcp add --scope user forgejo /path/to/target/release/forgejo-mcp-rs \
  --env FORGEJO_URL=https://codeberg.org \
  --env FORGEJO_TOKEN_READ_ONLY=your_read_token_here
# add --env FORGEJO_TOKEN_WRITE=… only if you want the (gated) write tools
# add --env FORGEJO_MIGRATE_TOKEN=… only to migrate from a *private* source instance

Or Claude Desktop

{
  "mcpServers": {
    "forgejo": {
      "command": "/path/to/target/release/forgejo-mcp-rs",
      "env": { "FORGEJO_URL": "https://codeberg.org", "FORGEJO_TOKEN_READ_ONLY": "your_read_token_here" }
    }
  }
}

Point FORGEJO_URL at a Gitea instance and everything works the same way — the flavor is detected for you:

{
  "mcpServers": {
    "gitea": {
      "command": "/path/to/target/release/forgejo-mcp-rs",
      "env": { "FORGEJO_URL": "https://gitea.com", "FORGEJO_TOKEN_READ_ONLY": "your_read_token_here" }
    }
  }
}

Logs go to stderr (stdout is the MCP transport); control verbosity with RUST_LOG, e.g. RUST_LOG=forgejo_mcp_rs=debug.

Tools

Grouped by subject. The second column marks the tools that need write mode.

Account and instance

Tool		Notes
whoami	read	The authenticated user (verifies the token)
version	read	This MCP server's version, the connected instance's version, and its flavor (forgejo or gitea)
list_orgs	read	Organizations you belong to
list_notifications	read	Your notification threads, slimmed (all=true for read+unread)
list_keys	read	An account's SSH and GPG keys (omit username for yourself). verified decides whether a signature can verify at all — but Gitea omits the field on SSH keys, so absent means unreported, not unverified. GPG entries carry the addresses the key covers and whether each is activated

Write-mode switches

Tool		Notes
write_status	read	Report write-mode state (token configured? active? minutes left?)
enable_write_mode / disable_write_mode		Enter/leave the time-boxed write mode

Repositories

Tool		Notes
list_my_repos	read	Your repositories (auto-paginated, slimmed)
search_repos	read	Repository search by keyword
get_repo	read	One repository's details (incl. default branch, size in KiB, and the has_* unit toggles), slimmed
create_repo	write	Create a repo (defaults to private)
edit_repo	write	Edit repo settings — visibility, description, website, default branch, unit toggles (issues, PRs, wiki, releases, actions, packages, projects), archive. Only provided fields change; no renames. A unit that is off 404s its whole endpoint family rather than returning empty results, so has_releases / has_actions are what to set when those tools report a repo as missing when it plainly exists
delete_repo	write	Delete a repo (needs confirm = "owner/repo")
migrate_repo	write	Copy a repo in from another instance — the only tool that carries issues/PRs across instances. Answers once the import has finished, and names any empty repository a failure left behind; leaves the source untouched; credential from FORGEJO_MIGRATE_TOKEN

Files

Tool		Notes
get_repo_tree	read	A repository's git tree (optional sha, recursive). Entries are path/type/size/sha; check truncated before concluding a file is absent
get_file_contents	read	Read a file (decodes text) or list a directory (owner/repo/path, optional ref). Optional start_line/end_line take a 1-indexed inclusive window, clamped to the file; total_lines is always reported
create_or_update_file	write	Create a file, or replace its content, as one commit (owner/repo/path/content as UTF-8 text). Pass the current sha from get_file_contents to update; a stale one is refused. Optional message, branch, new_branch
delete_file	write	Delete a file as one commit (owner/repo/path/sha). Optional message, branch, new_branch

Branches and commits

Tool		Notes
list_branches	read	Branches in owner/repo (auto-paginated, slimmed to name/commit/protected)
list_branch_protections	read	A repository's protection rules: what each enforces (require_signed_commits, direct pushes, approvals, status checks) for a branch name or glob. Allowlists omitted; an empty list means nothing is protected
create_branch	write	Create a branch (owner/repo/new_branch, optional old_ref)
delete_branch	write	Delete a branch (owner/repo/branch). The forge refuses the default and protected branches
list_commits	read	Commits on a ref (owner/repo, optional sha and path; auto-paginated). Slimmed to sha, subject, author, date and signature state — the raw objects carry base64 signature/payload blobs and per-commit files/stats
get_commit	read	One commit (owner/repo/sha), same fields. signature is verified, unverified or unsigned; signer on the first, reason on the second
get_commit_statuses	read	Individual statuses against a commit/branch/tag: context, status, description, target_url. get_combined_status rolls these into one verdict
get_combined_status	read	The rolled-up CI verdict for a ref — one state plus the latest per check. The tool for "did CI pass?"; get_commit_statuses gives the transition history

Issues

Tool		Notes
list_issues / get_issue	read	Issues in owner/repo (open by default), without the pull requests the forges also list as issues. Filter by labels, milestones, author, assignee, mentioned, search, and since/before; an unknown label or milestone name is refused, since the forge would list everything. sort (oldest, recentupdate, mostcomment, nearduedate, …) works on Forgejo; Gitea's issue listing has none, so it is refused there. Slimmed: state, author, labels, assignees, milestone, comment count and dates; get_issue adds the body
list_issue_comments	read	Comments on an issue/PR (slimmed)
create_issue	write	Create an issue (owner/repo/title, optional body)
edit_issue	write	Edit an issue in place (owner/repo/index): state open/closed, title, body, assignees, milestone, due_date, labels (names). Only what is passed changes; works on a pull request's number too, so state: closed closes a PR unmerged
comment_on_issue	write	Comment on an issue/PR (owner/repo/index/body)

Pull requests

Tool		Notes
list_pull_requests / get_pull_request	read	Pull requests in owner/repo (open by default); filter by base and head branch (head may be owner:branch) to ask whether a branch already has an open pull request, and by author; sort by oldest, recentupdate, recentclose, mostcomment and others, on both forges. Slimmed: branches, state, head_sha, author, labels and dates; get_pull_request adds the description, reviewers and merge details
list_pull_request_files	read	Files a PR changes (auto-paginated), with per-file additions/deletions and rename info. Forgejo omits the hunks here — use get_pull_request_diff for content
get_pull_request_diff	read	A PR's unified diff. file_path narrows it to one file (matching either side of a rename); otherwise truncated at 64 KiB, raise with max_bytes
list_pull_request_reviews	read	Reviews on a PR — approve/request-changes/comment verdicts + summary bodies (inline comments as a count)
create_pull_request	write	Open a PR (owner/repo/title/head/base, optional body)
create_pull_request_review	write	Review a PR (owner/repo/index/verdict): approve, request_changes or comment, with a summary body and optional commit_id
merge_pull_request	write	Merge a PR (owner/repo/index): style merge/rebase/rebase-merge/squash/fast-forward-only, optional title/message, delete_branch, and a head_sha guard that refuses the merge if the head moved. Answers with the PR as it now stands

Actions (CI)

Tool		Notes
list_workflow_runs	read	Actions (CI) runs in owner/repo, slimmed to one shape on both forges; newest first, 30 to a page by default; filter by head_sha/ref/status/event/workflow_id. Outcome is in each run's status
get_workflow_run	read	One workflow run by run_id, in list_workflow_runs' shape
list_workflow_jobs	read	The jobs of one run, normalized on both forges; each job's id is what get_job_log takes. Forgejo 16+
get_job_log	read	Part of one job's log, fetched by HTTP Range — the last 32 KiB by default (max_bytes up to 1 MiB), cut to whole lines, colour codes and timestamps stripped. earlier / later give the next window to ask for. Forgejo 16+
dispatch_workflow	write	Trigger an Actions workflow via workflow_dispatch (owner/repo/workflow file name/ref, optional inputs); returns the created run on Forgejo, an acknowledgement on Gitea
cancel_workflow_run	write	Cancel a pending or running run (owner/repo/run_id); answers with the run as it now stands. Forgejo 16+
rerun_workflow	write	Rerun a finished run, or with job_id one job and the jobs that depend on it; answers with the run. Forgejo 17+ — an instance without the endpoint is reported as such, with its version, and nothing is rerun

Releases

Tool		Notes
list_releases	read	A repo's releases, newest first (auto-paginated), slimmed to identity plus asset_count and asset_names
get_release	read	One release by git tag — the lookup that makes a release script idempotent. The same slim shape, plus the notes and target_commitish
list_release_assets	read	A release's attached files (id, name, size, download URL) by release_id
create_release	write	Create a release on a tag (tag_name; target_commitish creates the tag when it does not exist)
edit_release	write	Edit a release in place by release_id — body (the notes), name, tag_name, draft, prerelease. Only the fields passed are sent, so omitting one leaves it alone
upload_release_asset	write	Attach a local file to a release. Confined to FORGEJO_UPLOAD_ROOT; disabled entirely when that is unset
delete_release_asset	write	Remove one asset by attachment_id — needed to replace a same-named file, which Forgejo would otherwise keep alongside

Push mirrors

Tool		Notes
list_push_mirrors	write	List a repo's push mirrors (admin-scoped; secrets never returned)
add_push_mirror	write	Auto-push a repo to an external remote (e.g. a GitHub mirror); credential from FORGEJO_MIRROR_TOKEN or use_ssh=true
delete_push_mirror	write	Remove a push mirror by remote_name
sync_push_mirrors	write	Trigger an immediate push-mirror sync

Paging and slimming

Read list tools accept optional state (open/closed/all) and page/limit. Called with no paging, list_my_repos / list_issues / list_pull_requests auto-paginate the whole set and return a { returned, total, truncated, items } envelope; pass an explicit page or limit for a single page, which returns { page, limit, returned, total, items } instead (total is null for search_repos, which reports no count). Results are slimmed to the fields that matter, and a write answers in the shape of the matching read tool. The write tools require write mode.

Moving a repo between instances

migrate_repo wraps Forgejo's POST /repos/migrate, which you call on the destination — clone_addr points at the source. Unlike a push mirror, which replicates git refs and nothing else, this can bring the issues, PRs, labels, milestones, releases and wiki with it. Three things to know:

• Set service. It defaults to git, a bare clone that copies refs only. Name the source forge (gitea for a Forgejo or Codeberg source — there is no forgejo value) to enable the API-based importer that the metadata flags depend on.
• The content flags default to off. issues, pull_requests, labels, milestones, releases, wiki and lfs are each opt-in, matching the API's own defaults.
• It finishes within the call, and it's a copy. The instance answers once the import is done (seconds for a small repository on Codeberg). A failed import can leave an empty repository under the new name, which blocks a retry; the error names it, and it has to be deleted first. The source repository is never modified — retiring it is a separate, deliberate step.

Pass mirror: true to keep the result as a pull mirror that periodically re-fetches from the source, instead of taking a one-shot copy.

For a private source, set authenticate: true and the server sends FORGEJO_MIGRATE_TOKEN as the credential: as a token for gitea, github, gitlab, gogs and gitbucket, and as the clone password for git (with auth_username, default oauth2), onedev and codebase (which need auth_username). A username is refused for the token services, because their importers then ignore the token and the migration fails. As with push mirrors, the token is never a tool argument, so it stays out of the conversation. See Migration source token for how to mint and scope it — and for where it ends up, which is not where the other tokens go.

Release assets

Notes that were written before the build finished are corrected with edit_release, not by recreating the release — deleting one takes its assets with it. It sends only the fields you pass, so changing the body leaves the title and draft state untouched.

Publishing a build is three calls: look the tag up with get_release, create_release if that 404s, then upload_release_asset per file. Re-running is safe as long as you delete a same-named asset first — Forgejo keeps both otherwise, rather than replacing. The release shows only its asset names; list_release_assets gives the attachment_id to delete by.

upload_release_asset is the only tool that reads the local disk, and whatever it reads becomes a publicly downloadable file. So it is confined rather than trusted:

• Off unless configured. With FORGEJO_UPLOAD_ROOT unset, every upload is refused. There is deliberately no fallback to the working directory: an MCP server's cwd is whatever its client happened to launch it from, which is no basis for deciding what may be published.
• Confined to that root. The path is resolved through symlinks before the check, so neither a .. traversal nor a symlink pointing out of the tree escapes it.
• Bounded. Regular files only, at most FORGEJO_UPLOAD_MAX_MB (default 100).
• Plain names only. The published name defaults to the file's own and may not contain path separators, since Forgejo takes it verbatim.

Point the root at the tree you actually release from, not at $HOME:

"env": {
  "FORGEJO_UPLOAD_ROOT": "/Users/you/Developer",
  "FORGEJO_UPLOAD_MAX_MB": "100"
}

Forgejo vs Gitea

The server talks to both from one binary, detecting the flavor from GET /version. Of the ~25 endpoints it calls, the two forges agree on all but Actions — but where they disagree, they disagree completely, so this is the reference for what gets translated and what does not.

Everything below was checked against the two published specs, codeberg.org/swagger.v1.json and gitea.com/swagger.v1.json, compared definition by definition. The three points marked live could not have come from the specs at all: they type the fields in question as bare strings.

A workflow run is a different object on each forge

Gitea copied GitHub's vocabulary, Forgejo kept its own. The definitions are not even named alike — Forgejo's ActionRun against Gitea's ActionWorkflowRun — and of the fields worth reading, only id, event and html_url are spelled the same:

what it is	Forgejo	Gitea	this server
run counter	index_in_repo	run_number	run_number
title	title	display_title	title
outcome	status	conclusion	status
phase	—	status	folded into status
workflow file	workflow_id	file part of path	workflow
ref	prettyref	head_branch, or the ref in path	ref
commit	commit_sha	head_sha	commit_sha
who triggered it	trigger_user	trigger_actor, actor	dropped (carries an email)
times	started, stopped, created	started_at, completed_at, created_at	started, stopped, created

Three things are visible only from live data:

• live — path is not a path. Gitea reports ci.yml@refs/heads/main: workflow file, @, fully qualified ref. Reading it as a file path yields head as the "workflow", which is what this server's first live probe returned.
• live — head_branch is null for tag and pull-request runs, so the ref has to come out of path.
• live — unset means "", not null. A running Gitea run has conclusion: "" and completed_at: "". A consumer that decodes those as dates fails on the empty string, so a single queued run can fail a whole listing.

Gitea's status reports only queued / in_progress / completed, with the result arriving separately in conclusion once the run ends. This server promotes the conclusion into status, where Forgejo already puts the outcome, and keeps it verbatim alongside, so "did this pass?" is one question on both.

The output field names in the last column are this server's own, not either forge's. Do not read them as the wire format.

Requests differ too

An unknown query parameter is ignored rather than rejected, so the wrong spelling returns unfiltered results instead of an error:

filter	Forgejo	Gitea
git ref	ref, fully qualified	branch, bare name
workflow file	workflow_id query	a …/actions/workflows/{file}/runs path
head_sha, status, event	same	same

Unfiltered, the listing path is identical on both. dispatch_workflow differs as well: return_run_info is a Forgejo extension and Gitea rejects unknown body fields on that endpoint, so it is sent only to Forgejo — which is why Gitea answers with an acknowledgement rather than the run.

Everything else

Issues, pull requests, diffs, PR files, branches, contents, search, orgs, notifications, push mirrors and migration are identical in path, method and response shape. Each forge does carry fields the other lacks, but they are extras rather than disagreements — Forgejo has pronouns on a user and archive_download_count on a release; Gitea has time_estimate on an issue and branch_count on a repository.

The one real exception outside Actions is the contents endpoint, where each forge has a last-commit field the other does not:

	Forgejo	Gitea
when it last changed	last_commit_when	last_author_date, last_committer_date
the commit message	—	last_commit_message

This server does not read those fields, but anything rendering a file listing needs both spellings or the date column comes out blank on one forge.

Security

The token is read from the environment only — never logged, never written to disk (the client holds it in a zeroized buffer and marks the Authorization header sensitive). Read-only by default, so the server cannot modify your account without a separate write token and write mode. Tool output is untrusted, repo-derived text — the server flags it as data, not instructions. See SPECIFICATION.md.

The two remote credentials — FORGEJO_MIRROR_TOKEN and FORGEJO_MIGRATE_TOKEN — get the same in-process handling (environment only, zeroized, never a tool argument, never returned), but they are not header credentials and so do not stay between you and your own instance: each is sent to your instance in a request body and relayed onward to a third-party host, which sees it in cleartext. That is how Forgejo's mirror and migration APIs work, not a choice this server makes. Scope both narrowly and treat them as disclosed to the remote operator.

Quality checks

cargo fmt --all
cargo clippy --all-targets -- -D warnings
cargo test
cargo deny check          # cargo install cargo-deny

CI runs the same on Codeberg Forgejo Actions; a tracked .githooks/pre-push hook mirrors it locally (git config core.hooksPath .githooks).

History

Per-release changes are in CHANGELOG.md; the design rationale behind each is in SPECIFICATION.md.

Releases through v0.5 were built on the forgejo-api crate by Cyborus. forgejo-mcp-rs now talks to the Forgejo REST API through its own small client and carries no third-party forge SDK.

The companion Woodpecker CI server that shipped here as a second binary from v0.13.0 to v0.17.0 moved to its own repository at v0.18.0 — woodpecker-mcp.

License

MIT — see LICENSE.md for details.

MCP registry

Ownership-verification token for the MCP registry (read from this crate's rendered README on crates.io):

Registry ownership token: mcp-name: io.github.brechanbech/forgejo-mcp-rs