Forgejo Mcp

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 claudedesktopconfig.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)

| 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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Sqcows
• Source: Sqcows/forgejo-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.