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

Available Tools

Repository Management (24 tools)

| Tool | Description | |------|-------------| | search_repos | Search repositories | | get_repo | Get repository details | | create_repo | Create a new repository | | create_org_repo | Create repo in an organization | | delete_repo | Delete a repository | | fork_repo | Fork a repository | | list_branches | List branches | | get_branch | Get branch details | | create_branch | Create a branch | | delete_branch | Delete a branch | | list_repo_commits | List commits | | get_file_contents | Get file contents | | create_file | Create a file | | update_file | Update a file | | delete_file | Delete a file | | list_releases | List releases | | create_release | Create a release | | list_tags | List tags | | list_repo_topics | List topics | | update_repo_topics | Update topics | | list_forks | List forks | | list_collaborators | List collaborators | | add_collaborator | Add a collaborator | | transfer_repo | Transfer repository |

Issue Management (20 tools)

| Tool | Description | |------|-------------| | list_issues | List repository issues | | get_issue | Get issue details | | create_issue | Create an issue | | edit_issue | Edit an issue | | list_issue_comments | List issue comments | | create_issue_comment | Add a comment | | edit_issue_comment | Edit a comment | | delete_issue_comment | Delete a comment | | list_labels | List repository labels | | get_label | Get label details | | create_label | Create a label | | edit_label | Edit a label | | delete_label | Delete a label | | add_issue_labels | Add labels to issue | | remove_issue_label | Remove label from issue | | list_milestones | List milestones | | get_milestone | Get milestone details | | create_milestone | Create a milestone | | edit_milestone | Edit a milestone | | delete_milestone | Delete a milestone |

Pull Request Management (12 tools)

| Tool | Description | |------|-------------| | list_pull_requests | List pull requests | | get_pull_request | Get PR details | | create_pull_request | Create a pull request | | edit_pull_request | Edit a pull request | | merge_pull_request | Merge a pull request | | list_pr_commits | List PR commits | | list_pr_files | List changed files | | get_pr_diff | Get PR diff | | list_pr_reviews | List PR reviews | | create_pr_review | Create a review | | request_pr_review | Request reviewers | | update_pr_branch | Update PR branch |

Organization Management (14 tools)

| Tool | Description | |------|-------------| | list_orgs | List organizations | | get_org | Get org details | | create_org | Create organization | | edit_org | Edit organization | | delete_org | Delete organization | | list_org_repos | List org repositories | | list_org_members | List org members | | list_org_teams | List org teams | | get_team | Get team details | | create_team | Create a team | | add_team_member | Add team member | | remove_team_member | Remove team member | | list_org_labels | List org labels | | list_org_hooks | List org webhooks |

User Management (13 tools)

| Tool | Description | |------|-------------| | get_authenticated_user | Get current user | | get_user | Get user profile | | list_user_repos | List user repositories | | list_user_orgs | List user organizations | | search_users | Search users | | list_followers | List followers | | list_following | List following | | list_user_starred | List starred repos | | list_my_starred | List my starred repos | | star_repo | Star a repository | | unstar_repo | Unstar a repository | | list_my_notifications | List notifications | | mark_notifications_read | Mark all as read |

Admin & System (19 tools)

| Tool | Description | |------|-------------| | admin_list_users | List all users (admin) | | admin_create_user | Create user (admin) | | admin_delete_user | Delete user (admin) | | admin_edit_user | Edit user (admin) | | admin_list_cron_jobs | List cron jobs | | admin_run_cron_job | Run cron task | | admin_list_hooks | List system webhooks | | get_server_version | Get server version | | render_markdown | Render markdown | | render_markup | Render markup | | list_gitignore_templates | List gitignore templates | | get_gitignore_template | Get gitignore template | | list_license_templates | List license templates | | get_license_template | Get license template | | list_label_templates | List label templates | | get_label_template | Get label template | | get_nodeinfo | Get instance info | | list_action_runners_jobs | List action jobs | | get_runner_registration_token | Get runner token |

Security

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | FORGEJO_URL | Yes | Base URL of your Forgejo/Gitea instance | | FORGEJO_TOKEN | Yes | API token (generate at {your-instance}/user/settings/applications) | | FORGEJO_MCP_API_KEY | No | Bearer token for HTTP endpoint authentication | | RATE_LIMIT_MAX | No | Max requests per rate limit window (default: 100) | | RATE_LIMIT_WINDOW_MS | No | Rate limit window in ms (default: 60000) | | PORT | No | HTTP server port (default: 3000) |

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