Gitea MCP Server

Model Context Protocol server that provides ~200 auto-generated tools and resources for LLM agents to interact with Gitea and Forgejo instances. Built with FastMCP 3.x.

How it works

Your Gitea/Forgejo instance
       │
       ▼  (Swagger/OpenAPI spec)
  gitea-mcp-server
       │  ┌────────────────────────────┐
       │  │ Auto-generates ~200 tools  │
       │  │ from the API spec          │
       │  │ Adds lazy loading, scope   │
       │  │ filtering, annotations,    │
       │  │ workflow guides, resources │
       │  └────────────────────────────┘
       │
       ▼  (MCP protocol: stdio or HTTP)
  Your LLM agent
       │
       ├─ call_tool("gitea_issue_create_issue", ...)
       ├─ read_resource("gitea://repos/owner/repo")
       └─ search_tools("list pull requests")

Requirements

• Python 3.11+ and uv (package manager)

• A Gitea or Forgejo instance (local or remote)

• An API token with sufficient scopes (Settings → Applications → Generate Token)

Quick Start

git clone https://github.com/pxsloot/gitea-mcp-server.git && cd gitea-mcp-server
cp .env.example .env              # then edit GITEA_URL and GITEA_TOKEN
uv sync
uv run python -m gitea_mcp_server

Install from git (pip)

pip install git+https://github.com/pxsloot/gitea-mcp-server.git
gitea-mcp

Configuration

HTTP transport settings (TRANSPORT_TYPE=http):

• HTTP_HOST — default 127.0.0.1 (set HTTP_HOST=0.0.0.0 for remote access)

• HTTP_PORT — default 8080

• HTTP_PATH — default /mcp

• HTTP_CORS — defaults to origin from GITEA_URL

Usage

Stdio (CLI clients)

uv run python -m gitea_mcp_server

HTTP (server mode)

TRANSPORT_TYPE=http uv run python -m gitea_mcp_server
# Health check: http://localhost:8080/health
# MCP endpoint: http://localhost:8080/mcp

Docker

docker build --progress=plain -t gitea-mcp-server:latest .
docker run --rm -e GITEA_URL=... -e GITEA_TOKEN=... gitea-mcp-server:latest

For a local test Gitea instance: docker compose -f docker-compose.gitea.yml up -d

Key Features

• Auto-generated tools from Gitea's Swagger spec (converted 2.0 → 3.1)

• Lazy loading — BM25 search-based tool discovery, not all 200 tools listed upfront

• Permission filtering — tools hidden based on token scopes

• Workflow guides — 16 guides explaining Gitea/Forgejo concepts beyond the API

• MCP Resources — cached, URI-based data access (gitea://repos/{owner}/{repo})

• Tool annotations — read-only/destructive/idempotent hints per tool

• mcp_extensions.yaml — customize tool metadata without code

• HTTP/stdio transport, Docker support, OpenTelemetry observability

Development

# Tests
uv run pytest tests/unit/ -x -q

# Lint & type-check
uv run ruff check gitea_mcp_server/
uv run mypy gitea_mcp_server/

# Coverage
uv run pytest --cov=gitea_mcp_server

See docs/DEVELOPMENT.md and docs/ARCHITECTURE.md.

Contributing

Please read CONTRIBUTING.md for the full workflow. The AGENTS.md has detailed rules for agent contributors.

Changelog

See CHANGELOG.md for release history.

Security

Report vulnerabilities to gitea-mcp-server@pxsloot.nl — see SECURITY.md.

License

MIT — see LICENSE.