gitea-mcp

MCP server for Gitea -- full API coverage for autonomous AI agents.

Features

• ~290 operations covering the entire Gitea API surface

• Repositories, issues, pull requests, releases, labels, milestones

• File content management (create, read, update, delete)

• Branches, tags, commits, and status checks

• Actions / CI workflows and artifacts

• Long-running waiters - workflow_runs_wait / workflow_jobs_wait block until a run or job finishes (streaming progress via MCP notifications); non-blocking *_wait_start / *_wait_poll(max_block=...) / *_wait_cancel + waits_list keep the agent responsive. Waits tolerate transient API errors (max_poll_failures, default 3 consecutive), background waits self-terminate after max_lifetime (default 2h), and all wait ops live in gitea_read - they only ever GET

• Organizations, teams, and user management

• Webhooks, deploy keys, notifications, wiki, packages

• Admin endpoints for instance-level operations

• 6 risk-graded meta-tools (gitea_read / gitea_write / gitea_execute / gitea_delete / gitea_admin_read / gitea_admin_write) — agents pick a tool surface by the kind of side effect, not the HTTP verb

• Per-param help with operation='help' params={'search': 'foo'} for substring filtering and cross-group hints

• Zero-config install via uvx

Related MCP server: mcp-gitpro

Quick Start

Add the following to your MCP client configuration (Claude Desktop, Cursor, Claude Code, etc.). For Claude Code global config on macOS: ~/.claude.json → "mcpServers".

{
  "mcpServers": {
    "gitea": {
      "command": "uvx",
      "args": ["--refresh", "--extra-index-url", "https://nikitatsym.github.io/gitea-mcp/simple", "gitea-mcp"],
      "env": {
        "GITEA_URL": "https://gitea.example.com",
        "GITEA_TOKEN": "your-api-token"
      }
    }
  }
}

Or use the interactive Setup Page to generate the config.

Configuration

By default, creating public repos and orgs is blocked — agents must pass private=true explicitly. To allow public repos, add --allow-public to the command args:

"args": ["--refresh", "--extra-index-url", "https://nikitatsym.github.io/gitea-mcp/simple", "gitea-mcp", "--allow-public"]

Tool Groups

All ~290 operations are exposed through 6 risk-graded meta-tools — one tool surface per scope, dispatched via operation + params. Aligned with the v2 MCP spec so agents pick a tool by the kind of side effect, not the HTTP verb.

Each meta-tool takes operation (PascalCase op name, or help / schema) plus params (dict):

gitea_read(operation="help")                                                # list every op in this group
gitea_read(operation="help", params={"search": "merge"})                    # filter by substring; surfaces cross-group hits
gitea_read(operation="schema", params={"op": "GetRepo"})                    # full JSON Schema for one op
gitea_read(operation="GetRepo", params={"owner": "alice", "repo": "x"})     # invoke

gitea_write(operation="CreateIssue", params={"owner": "alice", "repo": "x", "title": "Bug", "body": "<brief>repro</brief>"})
gitea_execute(operation="MergePullRequest", params={"owner": "alice", "repo": "x", "index": 7, "merge_type": "squash"})

Params are validated strictly via Pydantic: unknown keys, wrong types, and missing required fields all surface as a ValueError with field-level detail.

Creating a Gitea API Token

1. Log in to your Gitea instance.

2. Go to Settings > Applications.

3. Under Manage Access Tokens, enter a token name (e.g. mcp-server).

4. Select the permissions your agent needs (read/write on repos, issues, etc.).

5. Click Generate Token and copy the value immediately -- it is shown only once.

Development

The project uses npm scripts for the local test lifecycle:

# unit tests (no docker, fast)
npm test

# bring up Gitea container + bootstrap admin user + write tests/.env
npm run gitea:up

# run integration tests against the live container
npm run test:integration

# tear down
npm run gitea:down

# one-shot: up + integration + down (exits with the pytest status code)
npm run test:integration:full

npm run gitea:bootstrap is idempotent — re-running against an already-bootstrapped instance no-ops if tests/.env carries a still-valid token, otherwise deletes the named token and creates a fresh one. The bootstrap script (scripts/bootstrap.py) is also runnable directly via uv run python scripts/bootstrap.py.

tests/.env schema:

GITEA_URL=http://localhost:3000
GITEA_TOKEN=<sha1>
GITEA_ADMIN_USER=testadmin
GITEA_ADMIN_PASSWORD=testadmin1234

Integration tests are gated behind @pytest.mark.integration and skipped unless GITEA_URL + GITEA_TOKEN are present — npm test will not require docker.

License

MIT