gitea-mcp

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

Features

• 186 tools 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
• Organizations, teams, and user management
• Webhooks, deploy keys, notifications, wiki, packages
• Admin endpoints for instance-level operations
• Zero-config install via uvx

Quick Start

Add the following to your MCP client configuration (Claude Desktop, Cursor, Claude Code, etc.):

{
  "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

Variable	Required	Description
GITEA_URL	Yes	Base URL of your Gitea instance (e.g. https://gitea.example.com)
GITEA_TOKEN	Yes	Personal access token with appropriate permissions

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.

Running Tests

The test suite runs against a real Gitea instance managed by Docker Compose.

# Start Gitea
docker compose -f tests/docker-compose.yml up -d

# Wait for Gitea to be ready, then run tests
uv run pytest tests/ -v

# Tear down
docker compose -f tests/docker-compose.yml down -v

License

MIT