Gitea MCP

A local MCP server that connects Claude directly to your own Gitea instance — no hosted gateway in between.

Most MCP setups for Git hosting route through a third-party gateway (Composio and similar): the gateway holds your token, brokers every API call, and sits as an opaque intermediary between your agent and your infrastructure. gitea_mcp skips that entirely. It runs as a subprocess on your own machine, talks over stdio, and speaks directly to your Gitea instance — your token and repo data never pass through anyone else's server.

Features

• Direct connection — talks straight to GITEA_BASE_URL, nothing in between

• Repositories — list and search

• Issues — list (filtered by state) and create

• Pull requests — list (filtered by state) and create

• Files — read content and write (create or update) as a single commit, with SHA-based conflict protection

• Commits — list history, optionally scoped to one file

• Actionable errors — auth, not-found, permission, conflict, and validation failures all come back as specific, readable messages instead of raw exceptions

Related MCP server: GitHub MCP Server

Prerequisites

• Python 3.9 or later

• A running Gitea instance you have API access to

• A Gitea personal access token

Install

python3 -m venv venv
source venv/bin/activate   # venv\Scripts\activate on Windows
pip install -r requirements.txt

Configure

Generate a token in Gitea under Settings → Applications → Generate New Token, scoped narrowly to what this server needs (repo read/write, issue read/write) rather than every permission available.

export GITEA_BASE_URL="https://gitea.example.com"
export GITEA_TOKEN="<your token>"

The server refuses to start if either variable is missing — no silent fallback to a hardcoded value.

Usage

Run standalone

python3 gitea_mcp.py

Add to Claude Desktop

In Claude Desktop's MCP config (claude_desktop_config.json):

{
  "mcpServers": {
    "gitea": {
      "command": "/path/to/venv/bin/python3",
      "args": ["/path/to/gitea_mcp.py"],
      "env": {
        "GITEA_BASE_URL": "https://gitea.example.com",
        "GITEA_TOKEN": "<your token>"
      }
    }
  }
}

Claude Desktop launches the server as a subprocess and talks to it over stdio — no port to open, no service to keep running.

Available tools

Scope

This is a first pass covering the core workflow — repos, issues, PRs, file read/write, and commit history. Branch management, releases, label administration, webhooks, and org-level operations aren't implemented yet. The plan is to expand once this core set proves out in real use rather than building everything speculatively up front.

Testing

tests/test_gitea_mcp.py exercises all 8 tools against a real Gitea instance — no mocking of the Gitea API.

pip install -r requirements-dev.txt
export GITEA_BASE_URL="https://gitea.example.com"
export GITEA_TOKEN="<your token>"
export TEST_REPO_OWNER="<owner of your scratch repo>"   # defaults to "dmc"
export TEST_REPO_NAME="<name of your scratch repo>"     # defaults to "gitea-mcp-test-repo"
pytest tests/ -v