Forgejo Mcp

Gitea/Forgejo MCP 服务

将 AI 变成代码仓库管理助手

一个 Model Context Protocol (MCP) 服务，可通过 Claude、Gemini 和 Copilot 等 AI 助手管理 Gitea/Forgejo 仓库。

🚀 为什么使用 Forgejo MCP 服务？

如果你想要：

• 智能进度跟踪：让 AI 帮你跟踪项目进度并分析瓶颈
• 自动 issue 分类：根据内容自动添加 issue 标签并设置里程碑
• 优先级排序：让 AI 分析 issue 内容，帮助确定任务优先级
• 代码审查辅助：在 Pull Request 中获取 AI 建议和洞察
• 项目文档整理：自动整理 Wiki 文档和发布说明

那么，这个工具正适合你！

✨ 支持的功能

Issue 管理

• 创建、编辑和查看 issue
• 添加、移除和替换标签
• 管理 issue 评论和附件
• 设置 issue 依赖关系

项目整理

• 管理标签（创建、编辑、删除）
• 管理里程碑（创建、编辑、删除）
• 搜索和列出仓库

发布管理

• 管理版本发布
• 管理发布附件

其他功能

• 查看 Pull Request
• 管理 Wiki 页面
• 查看 Forgejo/Gitea Actions 任务

📦 安装

方法 1：使用 docker（推荐）

对于 STDIO 模式，可以直接跳到 使用方法 部分。

对于 SSE/Streamable HTTP 模式，需要先将 forgejo-mcp 作为服务运行，然后再配置 MCP 客户端。

docker run -p 8080:8080 -e FORGEJOMCP_TOKEN="my-forgejo-api-token" ronmi/forgejo-mcp http --address :8080 --server https://git.example.com

方法 2：从源代码安装

go install github.com/raohwork/forgejo-mcp@latest

方法 3：下载预编译二进制文件

从 Releases 页面 下载适用于你操作系统的版本。

🖥️ 使用方法

此工具提供两种主要运行模式：用于本地集成的 stdio 和用于远程访问的 http。

在实际配置 MCP 客户端之前，你需要在 Forgejo/Gitea 服务端创建访问令牌。

1. 登录你的 Forgejo/Gitea 实例
2. 前往 Settings → Applications → Access Tokens
3. 点击 Generate New Token
4. 选择适当的权限范围（建议至少授予 repository 和 issue 的写入权限）
5. 复制生成的令牌

💡 提示：为确保安全，可考虑设置环境变量，而不是直接在配置中使用令牌：

export FORGEJOMCP_SERVER="https://your-forgejo-instance.com"
export FORGEJOMCP_TOKEN="your_access_token"

Stdio 模式（适用于本地客户端）

这是与 Claude Desktop 或 Gemini CLI 等本地 AI 助手客户端集成的推荐模式。它使用标准输入/输出进行直接通信。

配置 AI 客户端

使用 docker：

{
  "mcpServers": {
    "forgejo": {
      "command": "docker",
      "args": [
        "--rm",
        "ronmi/forgejo-mcp",
        "stdio",
        "--server", "https://your-forgejo-instance.com",
        "--token", "your_access_token"
      ]
    }
  }
}

从源代码安装或使用预编译二进制文件：

{
  "mcpServers": {
    "forgejo": {
      "command": "/path/to/forgejo-mcp",
      "args": [
        "stdio",
        "--server", "https://your-forgejo-instance.com",
        "--token", "your_access_token"
      ]
    }
  }
}

你可以查看 安全建议 部分，了解最佳实践。

HTTP 服务模式（用于远程访问）

此模式会启动 Web 服务，允许远程客户端通过 HTTP 连接。它适合 Web 服务，或为多个用户设置中央网关。

运行以下命令以启动服务：

# with local binary
/path/to/forgejo-mcp http --address :8080 --server https://your-forgejo-instance.com

# with docker
docker run -p 8080:8080 -d --rm ronmi/forgejo-mcp http --address :8080 --server https://your-forgejo-instance.com

服务支持两种运行模式：

• 单用户模式：如果启动时提供 --token（或环境变量 FORGEJOMCP_TOKEN），所有操作都会使用该令牌。

  forgejo-mcp http --address :8080 --server https://git.example.com --token your_token
  

• 多用户模式：如果未提供令牌，服务要求客户端在每次请求中发送 Authorization: Bearer <token> 标头，从而安全地为多个用户提供服务。

客户端配置

对于支持通过 HTTP 连接远程 MCP 服务的客户端，可以添加如下配置。此示例展示如何连接以多用户模式运行的服务：

{
  "mcpServers": {
    "forgejo-remote": {
      "type": "sse",
      "url": "http://localhost:8080/sse",
      "headers": {
        "Authorization": "Bearer your_token"
      }
    }
  }
}

或使用 http 类型（对于 Streamable HTTP，请在 URL 中使用不同的路径）

{
  "mcpServers": {
    "forgejo-remote": {
      "type": "http",
      "url": "http://localhost:8080/",
      "headers": {
        "Authorization": "Bearer your_token"
      }
    }
  }
}

如果连接的是单用户模式的服务，可以省略 headers 字段。

🛡️ 安全建议

1. 使用环境变量：设置 FORGEJOMCP_SERVER 和 FORGEJOMCP_TOKEN，然后从配置中移除 --server 和 --token
2. 限制令牌权限：仅授予必要的权限范围
3. 定期轮换令牌：定期更新访问令牌

📋 使用示例

配置完成后，你可以用自然语言让 AI 助手管理你的代码仓库：

"Show me critical bug reports of this repo on my gitea server"

"According to our discussion above, create a detailed issue about this bug, then leave a comment on the issue to describe how we will fix it."

"Give me a report about current milestone. Recent progression in particular."

"Analyze recent pull requests and tell me which ones need priority review"

🤝 支持与贡献

• 问题反馈：GitHub Issues
• 代码贡献：欢迎提交 Pull Request！

📄 许可证

本项目采用 Mozilla Public License 2.0 许可。

---

让 AI 成为你的代码仓库管理伙伴！ 🚀