# Gitea > Self-hosted Git server — manage repos, issues, and PRs from an AI agent. [Canonical HTML page](https://top-mcps.com/mcp/gitea) · [server.json](https://top-mcps.com/mcp/gitea.json) · [methodology](https://top-mcps.com/about/methodology) ## Install ### Claude Desktop — `claude_desktop_config.json` Paste under mcpServers. Fully quit and reopen Claude after editing. ```json { "mcpServers": { "gitea": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "GITEA_URL", "-e", "GITEA_TOKEN", "ghcr.io/kazuph/mcp-gitea:latest" ], "env": { "GITEA_URL": "${GITEA_URL}", "GITEA_TOKEN": "${GITEA_TOKEN}" } } } } ``` ### Claude Code — `CLI or .mcp.json` Run from your repo. Commit .mcp.json to share with your team. ```shell # export GITEA_URL=https://gitea.example.com # export GITEA_TOKEN=changeme claude mcp add gitea -- docker run --rm -i -e GITEA_URL -e GITEA_TOKEN ghcr.io/kazuph/mcp-gitea:latest ``` ### Cursor — `.cursor/mcp.json` Global path: ~/.cursor/mcp.json. Reload window after editing. ```json { "mcpServers": { "gitea": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "GITEA_URL", "-e", "GITEA_TOKEN", "ghcr.io/kazuph/mcp-gitea:latest" ], "env": { "GITEA_URL": "${GITEA_URL}", "GITEA_TOKEN": "${GITEA_TOKEN}" } } } } ``` ### VS Code — `.vscode/mcp.json` VS Code uses the "servers" key (not "mcpServers"). ```jsonc { "servers": { "gitea": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "GITEA_URL", "-e", "GITEA_TOKEN", "ghcr.io/kazuph/mcp-gitea:latest" ], "env": { "GITEA_URL": "${GITEA_URL}", "GITEA_TOKEN": "${GITEA_TOKEN}" } } } } ``` ### Windsurf — `~/.codeium/windsurf/mcp_config.json` Open via Cascade → hammer icon → Configure. ```json { "mcpServers": { "gitea": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "GITEA_URL", "-e", "GITEA_TOKEN", "ghcr.io/kazuph/mcp-gitea:latest" ], "env": { "GITEA_URL": "${GITEA_URL}", "GITEA_TOKEN": "${GITEA_TOKEN}" } } } } ``` ### Cline — `cline_mcp_settings.json` Open via the Cline sidebar → MCP Servers → Edit. ```json { "mcpServers": { "gitea": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "GITEA_URL", "-e", "GITEA_TOKEN", "ghcr.io/kazuph/mcp-gitea:latest" ], "env": { "GITEA_URL": "${GITEA_URL}", "GITEA_TOKEN": "${GITEA_TOKEN}" } } } } ``` ### Continue — `~/.continue/config.json` Continue uses modelContextProtocolServers with a transport block. ```json { "experimental": { "modelContextProtocolServers": [ { "transport": { "type": "stdio", "command": "docker", "args": [ "run", "--rm", "-i", "-e", "GITEA_URL", "-e", "GITEA_TOKEN", "ghcr.io/kazuph/mcp-gitea:latest" ], "env": { "GITEA_URL": "${GITEA_URL}", "GITEA_TOKEN": "${GITEA_TOKEN}" } } } ] } } ``` ### Codex CLI — `~/.codex/config.toml` Codex uses TOML. Each server is a [mcp_servers.] subtable. ```shell # ~/.codex/config.toml [mcp_servers.gitea] command = "docker" args = [ "run", "--rm", "-i", "-e", "GITEA_URL", "-e", "GITEA_TOKEN", "ghcr.io/kazuph/mcp-gitea:latest", ] env = { GITEA_URL = "${GITEA_URL}", GITEA_TOKEN = "${GITEA_TOKEN}" } ``` ### Zed — `~/.config/zed/settings.json` Zed calls them "context_servers". Settings live-reload on save. ```jsonc { "context_servers": { "gitea": { "command": { "path": "docker", "args": [ "run", "--rm", "-i", "-e", "GITEA_URL", "-e", "GITEA_TOKEN", "ghcr.io/kazuph/mcp-gitea:latest" ] }, "env": { "GITEA_URL": "${GITEA_URL}", "GITEA_TOKEN": "${GITEA_TOKEN}" } } } } ``` ### ChatGPT — `ChatGPT → Apps directory` Gitea doesn't ship a hosted HTTPS endpoint today. ChatGPT supports remote MCP servers only — to use this server in ChatGPT you'll need to deploy it to a public HTTPS URL first (e.g. via Cloudflare Workers or Vercel) or wait for an official remote build. ```none ``` ## At a glance - **Maintainer:** Community - **Transport:** stdio - **Auth model:** API key - **Required secrets:** GITEA_URL, GITEA_TOKEN - **Supported clients:** Claude, Cursor, VS Code, Windsurf, Any MCP-compatible client, Gitea 1.20+, Forgejo, Codeberg.org - **License:** MIT - **Language:** TypeScript - **Latest version:** latest - **Last verified:** 2026-06-02 - **Score:** 56/100 (rubric 2026-04 — see https://top-mcps.com/about/methodology) - **Source:** https://github.com/kazuph/mcp-gitea ## Tools & permissions | Tool | Description | Args | Side effects | |------|-------------|------|--------------| | `list_repos` | List repositories visible to the token. | `—` | read | | `get_repo` | Return metadata for a repo. | `owner: string, repo: string` | read | | `list_issues` | List issues in a repo. | `owner: string, repo: string` | read | | `create_issue` | Open an issue. Requires write scope. | `owner: string, repo: string, title: string, body?: string` | write | | `list_pull_requests` | List PRs in a repo. | `owner: string, repo: string` | read | ## Security & scope - **Access scope:** read-only - **Sandbox:** Authenticates with a Gitea personal access token scoped to the smallest set of permissions the workflow needs. The MCP defaults to read-only tools; writes require an explicit toggle. - **Gotchas:** - Tokens carry whatever permissions they were created with — always scope to a specific repo or org. - Self-hosted Gitea uses self-signed TLS by default; export GITEA_INSECURE=true only on internal-only hosts. - Gitea Actions have a different API surface from GitHub Actions; do not assume the same tool names. ## Quick answer **What it does.** Wraps the Gitea REST API for repository, issue, PR, label, and release operations — read by default, write behind explicit per-tool gates. **Best for:** - Self-hosted Git workflows - Issue triage and PR review - Release management on Gitea - Migrating a GitHub-centric agent stack to self-hosted - Forgejo + Codeberg users **Not for:** - Pure GitHub.com teams (use the GitHub MCP) - Workflows that need GitHub Actions (Gitea Actions has a different API) ## Description A community-maintained MCP that connects an AI agent to a self-hosted Gitea instance. Lists repositories, reads files and diffs, opens issues and pull requests, and manages labels and milestones. Designed for teams that run their own Git host on Gitea (or its Forgejo fork) and want the same agent ergonomics the GitHub MCP gives to GitHub users. ## Why it matters A real share of the self-hosted Git world runs Gitea or Forgejo. Without a Gitea MCP an agent has to drop to shell commands; with it, the same conversational workflow that ships on GitHub works on the team's own host. ## Key features - Gitea + Forgejo + Codeberg support - Repository, issue, PR, label, milestone tools - Read-only by default for unsafe operations - Per-host token auth - Works against self-hosted and Codeberg.org ## FAQ ### Does it work with Forgejo and Codeberg? Yes — Forgejo is an API-compatible Gitea fork; the MCP works against both. Point GITEA_URL at codeberg.org and a Codeberg token to use the public hosted Forgejo instance. ### Read-only or read-write? Read-only by default for write-heavy tools. Per-tool toggles let you opt into PR creation, comment posting, and label changes without exposing destructive operations like force-push. ### How is auth scoped? Use a personal access token created in the Gitea UI with the minimum scopes you need (repo:read for most workflows, repo:write only if the agent must open PRs). ## Changelog - **2026-06-02** — Refreshed install snippets and fact sheet; verified for 2026. - **2025-03-18** — Initial directory listing.