Gitea MCP Remote

An HTTP transport server that exposes Gitea operations via the MCP Streamable HTTP protocol for AI assistants like Claude Desktop. This server imports tools from the marketplace gitea-mcp-server package and serves them over HTTP with authentication and tool filtering.

Architecture

This is NOT a standalone MCP server. It imports tool definitions from the marketplace package and serves them:

1. Imports tools from gitea-mcp-server marketplace package
2. Serves via MCP Streamable HTTP protocol (/mcp endpoint)
3. Adds Bearer token authentication (optional)
4. Provides tool filtering (whitelist/blacklist)
5. Health check endpoints for monitoring

Claude Desktop (HTTP) ──▶ gitea-mcp-remote ──imports──▶ gitea-mcp-server ──API──▶ Gitea
                               │
                               ├── Authentication (Bearer token)
                               ├── Tool Filtering
                               └── MCP Streamable HTTP protocol

Features

• HTTP Transport: Exposes MCP server via HTTP for Claude Desktop
• Authentication: Optional Bearer token authentication
• Tool Filtering: Enable/disable specific tools for compatibility
• Docker Deployment: Production-ready containerization
• Health Checks: Monitoring endpoints (/health, /healthz, /ping)
• Async Architecture: Built on Starlette and uvicorn

Requirements

• Python >= 3.10
• Official gitea-mcp-server package (auto-installed as dependency)
• Gitea instance with API access
• Gitea API token with appropriate permissions

Quick Start with Docker

The easiest way to deploy is using Docker Compose with Caddy reverse proxy:

# 1. Clone the repository
git clone https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote.git
cd gitea-mcp-remote

# 2. Create .env file from template
cp docker/.env.example docker/.env

# 3. Edit .env with your Gitea credentials
nano docker/.env

# 4. Start the services (app + Caddy)
docker-compose -f docker/docker-compose.yml up -d

# 5. Check health
curl http://localhost/health

The server will be available at http://localhost (Caddy) or http://localhost:8080 (direct).

See DEPLOYMENT.md for detailed deployment instructions.

Installation

Option 1: Docker (Recommended)

See Quick Start above or DEPLOYMENT.md.

Option 2: From Source

# Clone the repository
git clone https://github.com/lmiranda/gitea-mcp-remote.git
cd gitea-mcp-remote

# Install the wrapper and its dependencies (including gitea-mcp-server)
pip install -e .

# Or use requirements.txt
pip install -r requirements.txt

For Development

Install with development dependencies:

pip install -e ".[dev]"

Configuration

The wrapper uses environment variables or a .env file for configuration.

Required Configuration

# Gitea Instance
GITEA_URL=https://gitea.example.com
GITEA_TOKEN=your_gitea_api_token_here
GITEA_OWNER=your_username_or_org

# Optional
GITEA_REPO=your_repo_name  # Can be omitted, specified per-request

# HTTP Server (defaults)
HTTP_HOST=0.0.0.0
HTTP_PORT=8080

Optional Configuration

# Bearer Authentication (optional but recommended)
AUTH_TOKEN=your_secret_bearer_token

# Tool Filtering (optional)
ENABLED_TOOLS=list_issues,create_issue,update_issue  # Whitelist mode
# OR
DISABLED_TOOLS=delete_issue,close_milestone  # Blacklist mode

Getting a Gitea API Token

1. Log into your Gitea instance
2. Navigate to Settings > Applications
3. Under "Generate New Token", enter a name (e.g., "MCP Wrapper")
4. Select appropriate permissions (minimum: read/write for repositories)
5. Click "Generate Token" and copy the token
6. Add the token to your .env file

Usage

Running the Server

With Docker

cd docker
docker-compose up -d

From Source

# Create .env file from template
cp .env.example .env
# Edit .env with your configuration
nano .env

# Run the server
gitea-mcp-remote
# Or use the startup script
./scripts/start.sh

The server will start on the configured host/port (default: http://0.0.0.0:8080).

HTTP Endpoints

Health Check

GET /health

Response: {"status": "ok"}

MCP Protocol Endpoint

The server implements the MCP Streamable HTTP protocol:

# Check protocol version
HEAD /mcp

# Send MCP JSON-RPC requests
POST /mcp
Content-Type: application/json
Accept: application/json, text/event-stream
Authorization: Bearer YOUR_TOKEN  # If auth enabled

# Example: Initialize
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}

# Example: List tools
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

# Example: Call tool
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_issues",
    "arguments": {
      "owner": "myorg",
      "repo": "myrepo",
      "state": "open"
    }
  }
}

With Claude Desktop

Configure Claude Desktop to use the HTTP wrapper:

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "gitea": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Available Tools

The wrapper exposes all tools from the official gitea-mcp-server. See the official Gitea MCP documentation for the complete list of available tools:

• Issues: List, get, create, update issues
• Labels: List, create labels
• Milestones: List, create milestones

Tool availability can be controlled via the ENABLED_TOOLS or DISABLED_TOOLS configuration.

Development

Setup Development Environment

# Install with development dependencies
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=gitea_mcp_remote

# Run specific test file
pytest tests/test_mcp_endpoints.py -v

Project Structure

gitea-mcp-remote/
├── src/gitea_mcp_remote/          # Main package
│   ├── __init__.py
│   ├── server_http.py             # MCP HTTP server
│   ├── config/                    # Configuration module
│   │   ├── __init__.py
│   │   └── settings.py
│   ├── middleware/                # HTTP middleware
│   │   ├── __init__.py
│   │   └── auth.py
│   └── filtering/                 # Tool filtering
│       ├── __init__.py
│       └── filter.py
├── tests/                         # Test suite (at repo root)
│   ├── conftest.py
│   ├── test_config.py
│   ├── test_filtering.py
│   ├── test_middleware.py
│   └── test_mcp_endpoints.py
├── docker/                        # Docker infrastructure
│   ├── Dockerfile
│   ├── docker-compose.yml
│   ├── Caddyfile
│   └── .env.example
├── scripts/                       # Utility scripts
│   ├── start.sh
│   └── healthcheck.sh
├── pyproject.toml                 # Project config
├── requirements.txt               # Dependencies
├── README.md                      # This file
├── CLAUDE.md                      # Claude Code guidance
└── DEPLOYMENT.md                  # Deployment guide

Deployment

For production deployment instructions, see DEPLOYMENT.md, which covers:

• Docker deployment
• Docker Compose orchestration
• Security best practices
• Monitoring and health checks
• Scaling considerations
• Cloud deployment (AWS, GCP, Azure)
• Kubernetes deployment

Troubleshooting

Authentication Errors

If you receive authentication errors:

1. Verify your GITEA_TOKEN is correct
2. Check that the token has appropriate permissions
3. Ensure your GITEA_URL does NOT include /api/v1 (wrapper adds it)
4. Verify the Gitea instance is accessible from the wrapper's network

HTTP 401/403 Errors

If Claude Desktop receives 401 or 403 errors:

1. Check that AUTH_TOKEN is configured (if authentication is enabled)
2. Verify Claude Desktop config includes the correct Authorization header
3. Check server logs for authentication failures

Connection Errors

If the wrapper cannot connect to Gitea:

1. Check that GITEA_URL is correct and accessible
2. Verify network connectivity to the Gitea instance
3. Check for firewalls or proxies blocking the connection
4. In Docker: Ensure the container can reach the Gitea host

gitea-mcp-server Not Found

If the wrapper fails to start with "gitea-mcp-server not found":

1. Verify gitea-mcp-server is installed: pip list | grep gitea-mcp
2. Install it manually: pip install gitea-mcp-server
3. In Docker: Rebuild the image

Tool Filtering Not Working

If tool filtering is not applied:

1. Check .env file syntax (no spaces around =)
2. Verify comma-separated list format
3. Check server logs for filter configuration
4. Send tools/list MCP request to see filtered tools

Security Considerations

• Always use HTTPS in production (configure reverse proxy)
• Set AUTH_TOKEN to secure the HTTP endpoint
• Rotate tokens regularly (both Gitea token and auth token)
• Use secrets management (not .env files) in production
• Limit network exposure (firewall, VPN, or private network)
• Monitor access logs for suspicious activity

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT License - see LICENSE file for details

Version

Current version: 2.0.0

Author

Leo Miranda

Links

• Repository: https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote
• Issues: https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues
• Marketplace Package: https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/mcp-servers/gitea
• MCP Documentation: https://modelcontextprotocol.io