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)

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