gitea-mcp

English | 中文文档

gitea-mcp is a Model Context Protocol (MCP) server that exposes Gitea repository operations as tools. Once connected to an MCP client (Claude Desktop, opencode, Cursor, etc.), an AI assistant can list, create, update, and delete issues, labels, milestones, and comments on your Gitea instance — all through natural language.

The server communicates over stdio and wraps the Gitea REST API (/api/v1).

Features

• Full Gitea project management — issues, labels, milestones, and comments via natural language

• Zero-config auto-discovery — reads baseUrl, owner, repo, and token from the project's git config; one global install serves many repos

• Multi-source auth with failover — tries [gitea] config tokens, GITEA_TOKEN, then the git credential store, advancing automatically on 401/403

• Action-scoped skills — ships one skill per workflow (find, create, label, comment, plan milestones, …) for opencode, Claude Code, Cursor, and more

• Client-agnostic — works with any stdio-based MCP client; ships guidance prompts and on-demand reference resources too

Related MCP server: forgejo-mcp

Table of Contents

• Features

• Requirements

• Installation

• Configuration

• MCP Client Setup

• Available Tools

• AI Guidance & Skills

• Development

• Contributing

• License

Requirements

• Node.js ≥ 24 — uses the global fetch

• A Gitea instance (self-hosted or Gitea Cloud) reachable over HTTP

• A Gitea API token (or a git credential-store entry) for anything beyond reading public repositories

Installation

From npm (npmjs.com)

npm install -g @amonstack/gitea-mcp

Or run directly without global install:

npx @amonstack/gitea-mcp

From GitHub Packages

Each release is also published to GitHub Packages. Route the @amonstack scope there once, then install:

echo "@amonstack:registry=https://npm.pkg.github.com" >> ~/.npmrc
npm install -g @amonstack/gitea-mcp

Build from source

git clone https://github.com/amonstack/gitea-mcp.git
cd gitea-mcp
npm ci
npm run build
node dist/cli.js

Configuration

All variables are optional — gitea-mcp auto-discovers the Gitea instance, repository, and token from the project's local git config so a single global install can serve many projects. Set them only to override the discovery.

How auto-discovery works

On start, gitea-mcp reads <cwd>/.git/config and derives:

• Instance URL — from the selected remote's host. SSH remotes (git@host:owner/repo) resolve to https://host. Override with GITEA_BASE_URL.

• owner / repo — from the selected remote's URL. Override with GITEA_DEFAULT_OWNER / GITEA_DEFAULT_REPO, or detect ad hoc with the resolve_repo tool.

• Remote selection — the upstream remote is preferred, falling back to origin, then any other remote. Both are reported by resolve_repo when they differ.

If the current directory has no git remote and GITEA_BASE_URL is not set, the server does not start — it prints a skip reason and exits 0. Run it from inside a cloned Gitea repository, or set GITEA_BASE_URL / GITEA_TOKEN explicitly.

Token discovery

gitea-mcp collects authentication candidates from three sources, in this priority order:

1. A [gitea "<baseUrl>"] section in .git/config (a bare [gitea] section is a host-wide fallback):

   [gitea "https://gitea.example.com"]
       token = <your-token>

   Always sent as Authorization: token <token>.

2. The GITEA_TOKEN environment variable — also sent as Authorization: token.

3. The git credential store (~/.git-credentials, or $XDG_CONFIG_HOME/git/credentials) — every line whose host matches the instance, e.g. https://alice:s3cret@gitea.example.com. When several lines match, the one whose path best matches owner/repo is tried first.

A credential-store entry's password field may hold a real PAT, an account password, or an OAuth token — git stores whatever was typed at the prompt, and the server cannot tell them apart statically. So each credential-store entry is tried under two authentication schemes:

• Authorization: Basic <base64(user:pass)> — works for account passwords and PATs alike (Gitea checks that the username matches the secret's owner).

• Authorization: token <secret> — works only for real PATs.

The order is chosen by a username heuristic: a convention username (oauth2, x-oauth-basic, or empty) tries token first; a real-looking username (e.g. alice) tries basic first.

Fault tolerance. On 401/403 the server advances to the next scheme/candidate and retries the same request; once a combination succeeds it is locked for the rest of the session (no re-probing). Non-auth errors (404, 500, network) propagate immediately and do not trigger a retry.

Diagnostics. The gitea_status tool (see Repository Helpers) returns a redacted view of the current state — which candidate is active, which are exhausted, the last status seen — without ever exposing the secret. Use it to troubleshoot a 401 instead of guessing.

If no source resolves a credential, the server still starts anonymously. Public repositories may be read; private repos and write operations return 401 — use the gitea-configure skill to guide setup, or set GITEA_TOKEN.

When GITEA_DEFAULT_OWNER and GITEA_DEFAULT_REPO are set, you can omit the owner and repo parameters in tool calls. The resolve_repo tool can also auto-detect them from a local git repository.

MCP Client Setup

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "gitea-mcp": {
      "command": "gitea-mcp",
      "env": {
        "GITEA_BASE_URL": "https://gitea.example.com",
        "GITEA_TOKEN": "your-token-here",
        "GITEA_DEFAULT_OWNER": "my-org",
        "GITEA_DEFAULT_REPO": "my-repo"
      }
    }
  }
}

If you built from source, use node /path/to/gitea-mcp/dist/cli.js instead.

opencode

Add to your opencode MCP configuration:

{
  "mcpServers": {
    "gitea-mcp": {
      "command": "gitea-mcp",
      "env": {
        "GITEA_BASE_URL": "https://gitea.example.com",
        "GITEA_TOKEN": "your-token-here"
      }
    }
  }
}

If you built from source, use node /path/to/gitea-mcp/dist/cli.js instead.

opencode and other AI tools can load native skills — one per action (find, create, update, label, comment, summarize, plan milestones, resolve repo) — that teach the assistant the safest workflow for that action, including pre-use checks and pitfalls. Install them once with the init command, targeting your tool (--tool, default opencode):

gitea-mcp init                      # opencode (global ~/.config/opencode/skills/)
gitea-mcp init --tool claude        # Claude Code (~/.claude/skills/)
gitea-mcp init --tool cursor        # Cursor (~/.cursor/skills/)
gitea-mcp init --project            # this project (./.<tool>/skills/)
gitea-mcp init --dir /exact/path    # custom location

Supported --tool values: amazon-q, antigravity, auggie, claude, cline, codex, codebuddy, continue, costrict, crush, cursor, factory, gemini, github-copilot, iflow, kilocode, opencode, qoder, qwen, roocode, windsurf. Paths follow each tool's conventional skills directory; use --dir for an exact location. Then restart your tool. See AI Guidance & Skills below.

Other MCP Clients

Any client that supports stdio-based MCP servers can use gitea-mcp. After installation, run it from inside a cloned Gitea repository (config is auto-discovered):

cd /path/to/your/gitea-repo
gitea-mcp

Or set the variables explicitly if you prefer:

export GITEA_BASE_URL="https://gitea.example.com"
export GITEA_TOKEN="your-access-token"
gitea-mcp

Available Tools

Issues

Comments

Labels

Milestones

Repository Helpers

AI Guidance & Skills

The server ships guidance so assistants use the tools correctly and safely, through three channels:

• instructions (on connect) — a concise strategy the server sends during the MCP handshake; capable clients inject it into the system prompt automatically.

• Tool descriptions — every tool's description flags its key risk (pagination, label ID-vs-name, destructive scope) and a minimal usage example.

• Prompts & resources — workflow templates (triage_issues, summarize_issue, audit_labels, milestone_report) and on-demand reference docs (field reference, label guide, tool cookbook) for clients that surface them.

Action skills

For opencode and other tools, the server ships a set of action-scoped skills — one per workflow, so the assistant loads only the guidance it needs (and never, say, delete instructions while creating). Install them with the gitea-mcp init --tool <name> command shown above.

Each skill is a short, AI-facing action flow (purpose, when to use, when not to, rules, and what to check first). The create, comment, and milestone skills also embed body templates (bug / feature / performance issue, comment, milestone) that standardize the format of what the assistant writes. Destructive single-tool actions (delete issue / comment / label / milestone) are intentionally left to the tool descriptions so they never contaminate a creative workflow.

Development

git clone https://github.com/amonstack/gitea-mcp.git
cd gitea-mcp
npm ci

For the full architecture — module layout, dependency graph, core patterns, and the guide to adding a new tool — see docs/architecture.md.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines on reporting bugs, suggesting features, and submitting pull requests.

License

MIT — Copyright (c) 2026 amonstack.