Codeberg MCP server

codeberg-mcp

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).

Why

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.

Architecture

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

Install

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)

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.

Usage

Claude Code (stdio)

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.)

claude.ai custom connector (HTTP)

MCP_TRANSPORT=http PORT=8000 python server.py
# exposes streamable-HTTP on http://0.0.0.0:8000

Tools (51)

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.

Error contract

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.

Development

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).

License

MIT — see LICENSE. crafted by effece 🧉