Admin
f0f724ec82
Some checks failed
Release / build (amd64, linux) (push) Successful in 5s
Release / build (arm64, darwin) (push) Successful in 7s
Release / build (amd64, windows) (push) Failing after 12s
Release / build (amd64, darwin) (push) Failing after 13s
Release / build (arm64, linux) (push) Successful in 18s
Release / release (push) Has been skipped
MCP (Model Context Protocol) server that enables AI assistants like Claude to interact with Gitea Actions. Features: - Query runners with status and capabilities - List and inspect workflow runs - Get job logs - List releases and assets Copyright 2026 MarketAlly Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
134 lines
4.1 KiB
Markdown
134 lines
4.1 KiB
Markdown
# 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
|