forgejo-mcp

A Model Context Protocol (MCP) server for Forgejo and Gitea instances. Enables AI assistants like Claude, Cursor, and other MCP-compatible tools to interact with your Forgejo/Gitea repositories, issues, pull requests, and more.

Features

• Comprehensive API coverage (103 tools across 6 categories)

• Configurable base URL - works with any Forgejo or Gitea instance

• Both stdio and HTTP transport modes

• Token-based authentication with optional HTTP Bearer auth

• Input validation and security hardening (path traversal protection, SSRF prevention, rate limiting)

• Docker support with security-hardened container

Quick Start

Prerequisites

• Node.js 18+

• A Forgejo or Gitea instance

• API token (generate at {your-instance}/user/settings/applications)

Installation

npm install -g @ric_/forgejo-mcp

Or run directly:

npx @ric_/forgejo-mcp

Configuration

Set environment variables:

export FORGEJO_URL=https://your-forgejo-instance.com
export FORGEJO_TOKEN=your-api-token

Or pass as CLI args:

npx @ric_/forgejo-mcp --url https://your-instance.com --token your-token

Usage

With Claude Code

You can add the MCP server using the CLI:

claude mcp add-json forgejo '{"command":"npx","args":["@ric_/forgejo-mcp"],"env":{"FORGEJO_URL":"https://your-instance.com","FORGEJO_TOKEN":"your-token"}}'

Or manually edit the config file:

• Project scope (shared with team): .mcp.json in your project root

• User scope (personal, all projects): ~/.claude.json

Add the following to the mcpServers object:

{
  "mcpServers": {
    "forgejo": {
      "command": "npx",
      "args": ["@ric_/forgejo-mcp"],
      "env": {
        "FORGEJO_URL": "https://your-instance.com",
        "FORGEJO_TOKEN": "your-token"
      }
    }
  }
}

You can verify the server is connected by running /mcp inside Claude Code.

With Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "forgejo": {
      "command": "npx",
      "args": ["@ric_/forgejo-mcp"],
      "env": {
        "FORGEJO_URL": "https://your-instance.com",
        "FORGEJO_TOKEN": "your-token"
      }
    }
  }
}

HTTP Mode

For remote/shared access:

FORGEJO_URL=https://your-instance.com \
FORGEJO_TOKEN=your-token \
FORGEJO_MCP_API_KEY=your-secret-api-key \
npx @ric_/forgejo-mcp-http --port 3000

Endpoint: http://localhost:3000/mcp

Authentication: Set FORGEJO_MCP_API_KEY to require Bearer token authentication on the HTTP endpoint. Clients must include Authorization: Bearer your-secret-api-key in requests. If not set, the endpoint is unauthenticated (only suitable for localhost or behind a reverse proxy).

Rate Limiting: Enabled by default at 100 requests/minute per IP. Configure via:

• RATE_LIMIT_MAX - max requests per window (default: 100)

• RATE_LIMIT_WINDOW_MS - window size in milliseconds (default: 60000)

Docker

Pull from Docker Hub:

docker run -p 3000:3000 \
  -e FORGEJO_URL=https://your-instance.com \
  -e FORGEJO_TOKEN=your-token \
  -e FORGEJO_MCP_API_KEY=your-secret-key \
  richarvey/forgejo-mcp

Or use docker-compose:

cp .env.example .env
# Edit .env with your values, then:
docker compose up -d

Or build from source:

docker build -t forgejo-mcp .
docker run -p 3000:3000 \
  -e FORGEJO_URL=https://your-instance.com \
  -e FORGEJO_TOKEN=your-token \
  -e FORGEJO_MCP_API_KEY=your-secret-key \
  forgejo-mcp

The Docker image:

• Uses multi-stage build for minimal image size

• Runs as non-root user

• Read-only filesystem

• No new privileges security option

Auto Setup

When an MCP client (such as Claude Code, Claude Desktop, or Cursor) connects to this server, it automatically receives instructions describing all available tool categories and usage conventions. This means the AI assistant understands how to use the server without any additional prompting — it knows which tools exist, that most require owner and repo parameters, how pagination works, and that file content should be base64-encoded.

No configuration is needed to enable this; it works out of the box via the MCP initialize handshake.

Available Tools

Repository Management (24 tools)

Issue Management (20 tools)

Pull Request Management (12 tools)

Organization Management (14 tools)

User Management (13 tools)

Admin & System (19 tools)

Security

Environment Variables

Security Features

• Input validation - All parameters validated with Zod schemas (path traversal prevention, regex-validated usernames, bounded pagination, enum enforcement)

• SSRF protection - Base URL validated against cloud metadata endpoints and private IP ranges

• HTTP authentication - Optional Bearer token auth for the HTTP transport

• Rate limiting - Per-IP rate limiting on HTTP endpoints

• Token safety - API tokens never leaked in error messages; URLs sanitized in errors

• Security headers - X-Content-Type-Options: nosniff, X-Frame-Options: DENY

• Non-root Docker - Container runs as unprivileged user with read-only filesystem

Best Practices

• Always use HTTPS for your Forgejo instance URL

• Use short-lived API tokens with minimal required permissions

• Set FORGEJO_MCP_API_KEY when running HTTP mode on a network

• Admin tools require an admin-level Forgejo token - use a non-admin token if you don't need them

Development

git clone https://code.squarecows.com/SquareCows/forgejo-mcp.git
cd forgejo-mcp
npm install
npm run dev          # stdio mode
npm run dev:http     # HTTP mode
npm test             # run tests
npm run build        # compile TypeScript

Compatible Instances

This MCP server works with:

• Forgejo (v7.0+)

• Gitea (v1.20+)

• Codeberg

• Any Gitea-compatible forge

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT - see LICENSE