Forgejo MCP

🚀 Gitea/Forgejo MCP Server

这是一个 模型上下文协议（Model Context Protocol，MCP） 服务器，可让你通过 Claude、Gemini 和 Copilot 等 AI 助手来管理 Gitea/Forgejo 代码仓库。借助它，AI 能成为你的代码仓库管理助手。

🚀 快速开始

为何使用 Forgejo MCP 服务器？

如果你有以下需求：

• 智能进度跟踪：让 AI 帮你跟踪项目进度并分析瓶颈。
• 自动问题分类：根据问题内容自动添加标签并设置里程碑。
• 优先级排序：让 AI 分析问题内容，帮助你对任务进行优先级排序。
• 代码审查辅助：在拉取请求（Pull Request）中获取 AI 的建议和见解。
• 项目文档整理：自动整理 Wiki 文档和发布说明。

那么这个工具就是为你量身打造的！

✨ 主要特性

问题管理

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

项目组织

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

版本发布管理

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

其他特性

• 查看拉取请求。
• 管理 Wiki 页面。
• 查看 Forgejo/Gitea Actions 任务。

📦 安装指南

方法一：使用 Docker（推荐）

如果你使用的是 STDIO 模式，可以直接跳到使用说明部分。 如果你使用的是 SSE/可流式 HTTP 模式，在配置 MCP 客户端之前，你应该先将 forgejo-mcp 作为服务器运行。

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

方法二：从源代码安装

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

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

从 发布页面 下载适合你操作系统的版本。

💻 使用示例

基础用法

本工具提供两种主要操作模式：用于本地集成的 stdio 模式和用于远程访问的 http 模式。 在实际设置 MCP 客户端之前，你需要在 Forgejo/Gitea 服务器上创建一个访问令牌。

1. 登录到你的 Forgejo/Gitea 实例。
2. 转到设置 → 应用程序 → 访问令牌。
3. 点击生成新令牌。
4. 选择适当的权限范围（建议至少选择 repository 和 issue 的写入权限）。
5. 复制生成的令牌。

💡 使用建议

为了安全起见，考虑使用环境变量而不是直接在配置中使用令牌：

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

STDIO 模式（用于本地客户端）

这是与 Claude Desktop 或 Gemini CLI 等本地 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 的服务或为多个用户设置中央网关。 运行以下命令启动服务器：

# 使用本地二进制文件
/path/to/forgejo-mcp http --address :8080 --server https://your-forgejo-instance.com

# 使用 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 类型（对于可流式 HTTP，在 URL 中使用不同的路径）

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

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

高级用法

配置完成后，你可以在 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"

🔧 安全建议

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

🤝 支持与贡献

• 报告 Bug：GitHub Issues
• 代码贡献：欢迎提交拉取请求！

📄 许可证

本项目采用 Mozilla 公共许可证 2.0 进行许可。

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