Gitea MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to interact directly with your Gitea instance.

Features

• Query Runners - List runners, check status, view capabilities (OS, tools, disk space)
• Monitor Workflows - List runs, get job details, view logs
• Manage Releases - List releases, get assets, check download counts
• AI-Friendly - Structured JSON responses designed for AI consumption

Quick Start

1. Download

Download the latest binary from Releases.

2. Configure Claude Code

Add to your Claude Code settings:

Option A: Command line arguments

{
  "mcpServers": {
    "gitea": {
      "command": "/path/to/gitea-mcp-server",
      "args": ["--url", "https://git.marketally.com", "--token", "YOUR_API_TOKEN"]
    }
  }
}

Option B: Environment variables

{
  "mcpServers": {
    "gitea": {
      "command": "/path/to/gitea-mcp-server",
      "env": {
        "GITEA_URL": "https://git.marketally.com",
        "GITEA_TOKEN": "your-token-here"
      }
    }
  }
}

3. Use It

Ask Claude things like:

• "What runners are online?"
• "Show me the latest workflow runs for gitcaddy/act_runner"
• "Why did run #77 fail?"
• "What assets are in the v0.3.6 release?"

Available Tools

Tool	Description
list_runners	List all runners with status, capabilities, disk space
get_runner	Get detailed runner info by ID
list_workflow_runs	List workflow runs for a repository
get_workflow_run	Get run details with all jobs
get_job_logs	Get logs from a specific job
list_releases	List releases for a repository
get_release	Get release details with all assets

Building from Source

git clone https://git.marketally.com/gitcaddy/mcp-server.git
cd mcp-server
go build -o gitea-mcp-server .

Cross-compile for all platforms

# Linux
GOOS=linux GOARCH=amd64 go build -o gitea-mcp-server-linux-amd64 .

# macOS Intel
GOOS=darwin GOARCH=amd64 go build -o gitea-mcp-server-darwin-amd64 .

# macOS Apple Silicon
GOOS=darwin GOARCH=arm64 go build -o gitea-mcp-server-darwin-arm64 .

# Windows
GOOS=windows GOARCH=amd64 go build -o gitea-mcp-server-windows-amd64.exe .

Architecture

┌─────────────┐     stdio      ┌──────────────────┐     HTTP      ┌─────────────┐
│ Claude Code │ ◄────────────► │ gitea-mcp-server │ ◄───────────► │   Gitea     │
│  (AI Tool)  │   JSON-RPC     │   (This binary)  │  /api/v2/mcp  │   Server    │
└─────────────┘                └──────────────────┘               └─────────────┘

The MCP server:

1. Receives JSON-RPC requests over stdio from Claude Code
2. Forwards them to Gitea's /api/v2/mcp endpoint
3. Returns responses back to Claude Code

Configuration Options

Flag	Env Variable	Description
--url	GITEA_URL	Gitea server URL (required)
--token	GITEA_TOKEN	API token for authentication
--debug	-	Enable debug logging to stderr

Obtaining an API Token

1. Go to your Gitea instance → Settings → Applications
2. Generate a new token with appropriate scopes
3. Copy the token and use it in your configuration

Requirements

• Gitea 1.26+ with GitCaddy enhancements (includes /api/v2/mcp endpoint)
• Go 1.21+ (for building from source)

License

MIT License - See LICENSE file.

Related Projects

• GitCaddy Gitea - Enhanced Gitea fork with AI-friendly APIs
• GitCaddy act_runner - Enhanced runner with capabilities detection