# Gitea MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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](https://git.marketally.com/gitcaddy/mcp-server/releases).

### 2. Configure Claude Code

Add to your Claude Code settings:

**Option A: Command line arguments**
```json
{
  "mcpServers": {
    "gitea": {
      "command": "/path/to/gitea-mcp-server",
      "args": ["--url", "https://git.marketally.com", "--token", "YOUR_API_TOKEN"]
    }
  }
}
```

**Option B: Environment variables**
```json
{
  "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

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

### Cross-compile for all platforms

```bash
# 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](LICENSE) file.

## Related Projects

- [GitCaddy Gitea](https://git.marketally.com/gitcaddy/gitea) - Enhanced Gitea fork with AI-friendly APIs
- [GitCaddy act_runner](https://git.marketally.com/gitcaddy/act_runner) - Enhanced runner with capabilities detection