An MCP server for Codeberg (and any Gitea/Forgejo instance) exposing 51 tools for repos, files, pull requests, branches, commits, issues, releases, tags, Actions, and repo/account settings — with multi-account support and a consistent structured error contract.
Works with Claude Code (stdio transport) and claude.ai custom connectors (streamable-HTTP / SSE transport).
The official tooling around Forgejo/Gitea is thin, and switching between several
accounts (e.g. a personal account and an org) usually means juggling tokens by
hand. This server wraps the REST API behind typed MCP tools, routes each call to
the right account via a single account parameter, and turns API failures into
a predictable {"error": ..., "status": ...} shape so the agent can reason about
them instead of crashing.
flowchart LR
Agent[MCP client<br/>Claude Code / claude.ai]
Server[codeberg-mcp<br/>MCPServer server.py]
Accounts[(CODEBERG_ACCOUNTS<br/>name -> token)]
API[(Codeberg / Forgejo<br/>Gitea REST API v1)]
Agent -- "tool call (+optional account)" --> Server
Server -- "resolve account -> token" --> Accounts
Server -- "authenticated request" --> API
API -- "JSON or {error,status}" --> Server
Server -- "structured result" --> Agent
git clone https://github.com/effecet/codeberg-mcp.git
cd codeberg-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # then edit .env (see Configuration)All config is via environment variables (loaded from .env):
| Variable | Required | Description |
|---|---|---|
CODEBERG_ACCOUNTS |
yes | JSON {name: token} map. Generate tokens at https://codeberg.org/user/settings/applications. |
CODEBERG_DEFAULT_ACCOUNT |
no | Account used when a tool omits account. Defaults to the first key. |
MCP_TRANSPORT |
no | stdio | http (default) | sse. |
HOST / PORT |
no | Bind address for http/sse (default 0.0.0.0:8000). |
Token scopes depend on which tools you use: read/write:repository,
read/write:issue, read:user. A token missing a scope returns a clean 403
through the error contract rather than crashing.
Add to your MCP config (e.g. ~/.claude/.mcp.json):
{
"mcpServers": {
"codeberg": {
"command": "python",
"args": ["/path/to/codeberg-mcp/server.py"],
"env": { "MCP_TRANSPORT": "stdio" }
}
}
}(CODEBERG_ACCOUNTS can live in the repo's .env or be passed in env.)
MCP_TRANSPORT=http PORT=8000 python server.py
# exposes streamable-HTTP on http://0.0.0.0:8000| Group | Tools |
|---|---|
| Repos | list_repos, get_repo, create_repo, edit_repo, set_repo_actions_enabled |
| Files | get_file, create_file, update_file, delete_file, list_dir |
| Pull requests | list_pulls, get_pull, create_pull, merge_pull, list_pull_files, list_pull_commits, list_pull_reviews |
| Branches / commits | list_branches, create_branch, get_latest_commit, compare_refs |
| Issues | list_issues, get_issue, create_issue, edit_issue, comment_on_issue, list_issue_labels, add_issue_labels, remove_issue_label |
| Releases / tags | list_releases, get_release, get_release_by_tag, create_release, edit_release, list_tags, get_tag |
| Actions | list_workflow_runs, get_workflow_run, wait_for_runs, get_workflow_logs, cancel_workflow_run, rerun_workflow_run, list_runners, list_queued_jobs, list_actions_variables, get_actions_variable, create_actions_variable, update_actions_variable |
| Account / secrets | list_user_keys, list_user_emails, list_repo_secrets |
Every tool accepts an optional account parameter to pick which configured
account (token) to use.
wait_for_runs blocks until every Actions run for a commit has finished (up
to 30 minutes per call) and reports MCP progress while it waits, when the
client asks for it, so an agent can wait for CI without hand-rolled sleep
loops. get_workflow_logs returns one section per job, keeping the end of
each log, where the failure usually is. cancel_workflow_run and
rerun_workflow_run call endpoints that codeberg.org does not register (they
return 404 there); they work only on Forgejo/Gitea instances that expose them.
On any API failure a tool returns, instead of its normal result:
{"error": "Codeberg API <status>: <detail>", "status": <int|null>}Treat any result with top-level error and status keys as a failure. Tools
that normally return a list or text (or nothing) cannot return that object, so
they report an error result (isError: true) whose text is
Error executing tool <name>: followed by the same JSON.
Caller mistakes the caller can fix (unknown account, a directory passed to
get_file, an invalid merge method) come back as an error result with the
guidance as text. Any other failure inside a tool is a bug, and the client sees
only Error executing tool <name>.
status is null when there is no definite answer: a timeout, a refused or
dropped connection, a body that cannot be read, or a 502/503/504 from
Codeberg's gateway (which has applied writes before failing the response). A
write may still have landed, so check state before retrying.
create_pull and merge_pull do that check themselves. When the response is
lost they re-read the real state (open PRs for head→base; the PR's merged
flag, re-read over a few seconds because it lags), and if the PR or merge is
there they return success with recovered_after_read_error: true and the
original error in read_error. Do not retry those. If the re-check cannot
settle it, the result is still status: null. merge_pull also accepts
merge_title and merge_message for the merge or squash commit.
pip install -r requirements.txt
pytest -q # 165 tests (respx-mocked, no network)
ruff check .
ruff format --check .CI runs ruff + pytest on GitHub Actions (.github/workflows/ci.yml).
MIT — see LICENSE. crafted by effece 🧉