richarvey/forgejo-mcp

forgejo-mcp

为https://forgejo.org/%E5%92%8CGitea%E5%AE%9E%E4%BE%8B%E8%AE%BE%E8%AE%A1%E7%9A%84Model Context Protocol（MCP）服务器，允许Claude、Cursor等MCP兼容AI助手与你的Forgejo/Gitea仓库、issue、拉取请求等进行交互。

核心功能

• 全面API覆盖（6个类别共102个工具）
• 可配置基础URL（适配任何Forgejo/Gitea实例）
• 支持stdio和HTTP两种传输模式
• 基于令牌的认证（可选HTTP Bearer认证）
• 输入验证与安全加固（路径遍历防护、SSRF预防、速率限制）
• 安全加固的Docker容器支持

快速开始

前置条件

• Node.js 18+
• Forgejo或Gitea实例
• API令牌（在{你的实例地址}/user/settings/applications生成）

安装

bash
npm install -g @ric_/forgejo-mcp

或直接运行：

bash
npx @ric_/forgejo-mcp

配置

设置环境变量：

bash
export FORGEJO_URL=https://你的-forgejo-实例.com
export FORGEJO_TOKEN=你的-api-令牌

或通过CLI参数传递：

bash
npx @ric_/forgejo-mcp --url https://你的实例地址.com --token 你的令牌

使用场景

与Claude Code集成

通过CLI添加MCP服务器：

bash
claude mcp add-json forgejo '{"command":"npx","args":["@ric_/forgejo-mcp"],"env":{"FORGEJO_URL":"https://你的实例地址.com","FORGEJO_TOKEN":"你的令牌"}}'

或手动编辑配置文件：

• 项目范围（团队共享）：项目根目录下的.mcp.json
• 用户范围（个人所有项目）：~/.claude.json

在mcpServers对象中添加：

json
{
  "mcpServers": {
    "forgejo": {
      "command": "npx",
      "args": ["@ric_/forgejo-mcp"],
      "env": {
        "FORGEJO_URL": "https://你的实例地址.com",
        "FORGEJO_TOKEN": "你的令牌"
      }
    }
  }
}

在Claude Code中运行/mcp验证连接。

与Claude Desktop集成

添加到claude_desktop_config.json：

json
{
  "mcpServers": {
    "forgejo": {
      "command": "npx",
      "args": ["@ric_/forgejo-mcp"],
      "env": {
        "FORGEJO_URL": "https://你的实例地址.com",
        "FORGEJO_TOKEN": "你的令牌"
      }
    }
  }
}

HTTP模式（远程/共享访问）

bash
FORGEJO_URL=https://你的实例地址.com \
FORGEJO_TOKEN=你的令牌 \
FORGEJO_MCP_API_KEY=你的秘密-api-密钥 \
npx @ric_/forgejo-mcp-http --port 3000

端点：http://localhost:3000/mcp

认证：设置FORGEJO_MCP_API_KEY需在HTTP请求中包含Authorization: Bearer 你的秘密-api-密钥；未设置则端点无认证（仅适用于本地或反向代理后）。

速率限制：默认每分钟每IP 100次请求，可通过RATE_LIMIT_MAX（最大请求数）和RATE_LIMIT_WINDOW_MS（窗口毫秒数）配置。

Docker部署

从Docker Hub拉取：

bash
docker run -p 3000:3000 \
  -e FORGEJO_URL=https://你的实例地址.com \
  -e FORGEJO_TOKEN=你的令牌 \
  -e FORGEJO_MCP_API_KEY=你的秘密密钥 \
  docker.xuanyuan.run/richarvey/forgejo-mcp

或使用docker-compose：

bash
cp .env.example .env
# 编辑.env填入你的值后运行：
docker compose up -d

或从源码构建：

bash
docker build -t forgejo-mcp .
docker run -p 3000:3000 \
  -e FORGEJO_URL=https://你的实例地址.com \
  -e FORGEJO_TOKEN=你的令牌 \
  -e FORGEJO_MCP_API_KEY=你的秘密密钥 \
  docker.xuanyuan.run/forgejo-mcp

Docker镜像特性：

• 多阶段构建（最小镜像体积）
• 以非root用户运行
• 只读文件系统
• 禁用新特权安全选项

安全特性

• 输入验证：所有参数通过Zod schema验证（路径遍历防护、用户名正则校验、分页限制、枚举强制）
• SSRF防护：验证基础URL避免访问云元数据端点和私有IP范围
• HTTP认证：可选Bearer令牌认证
• 速率限制：HTTP端点按IP限流
• 令牌安全：错误信息不泄露API令牌，URL在错误中被 sanitize
• 安全头：X-Content-Type-Options: nosniff、X-Frame-Options: DENY
• 非root容器：以非特权用户运行且文件系统只读

兼容实例

• Forgejo（v7.0+）
• Gitea（v1.20+）
• Codeberg
• 任何Gitea兼容的代码托管平台

许可证

MIT - 详见LICENSE