gitea-mcp

gitea-mcp

一个适用于 Gitea 的 Model Context Protocol 服务，可让 AI 助手（Claude、ChatGPT、Copilot，以及其他任何支持 MCP 的工具）在你能够访问的任何 Gitea 实例上读取、创建和管理问题、代码仓库及发行版。

也适用于 Forgejo 和 Codeberg（API 兼容）。

为什么选择它

可自托管的 Gitea 是一种广受欢迎的 GitHub 替代方案，适合个人开发者、小型团队和注重隐私的组织。安装此 MCP 服务后，你的 AI 助手可以：

• 不用离开聊天界面，就能将审计发现或重构备注创建为 Gitea 问题
• 使用自然语言对代码仓库中的未解决问题进行分类
• 在编码会话结束时创建发行版
• 一次性为多个代码仓库中的问题添加评论

功能

资源	工具
问题	create_issue、list_issues、get_issue、update_issue、add_comment
代码仓库	list_repos、list_labels、list_milestones、list_branches
拉取请求	list_pull_requests、get_pull_request、add_comment_on_pr、create_pr、merge_pr
文件	read_file、commit_changes、create_branch
发行版	list_releases、create_release
元信息	get_server_info、get_server_version

• 通过个人访问令牌（PAT）进行 Bearer 身份验证
• 使用 httpx 和 FastMCP 进行异步 HTTP 通信
• 适用于可自托管的 Gitea、Forgejo 和 Codeberg

快速开始

1. 安装

pip install gitea-mcp

或者使用 uv：

uv pip install gitea-mcp

2. 生成个人访问令牌

在你的 Gitea 实例中，前往 Settings → Applications → Generate New Token，并至少授予以下权限：

• read:repository
• write:issue
• read:user

如果还想创建发行版，请添加 write:repository。

3. 配置 MCP 客户端

**Claude Desktop（交互式）：**运行

gitea-mcp init

系统会提示你输入 Gitea URL 和个人访问令牌，验证连接，并为你的操作系统写入（或合并到）正确的 claude_desktop_config.json。重启 Claude Desktop 即可完成。

如需随时检查服务是否能够访问你的 Gitea 实例：

gitea-mcp doctor

doctor 会从环境中读取 GITEA_URL 和 GITEA_TOKEN，执行 GET /api/v1/user，并报告已验证身份的用户名以及 MCP 工具接口的状态。退出码 0 = 就绪；退出码 1 = 连接或加载失败；退出码 2 = 缺少配置。

**任何 MCP 客户端（手动配置）：**将 gitea-mcp 添加到客户端的 MCP 配置中。建议使用 uvx，这样客户端可以在隔离环境中启动最新发布的 wheel，无需将 gitea-mcp 放入客户端自身的 PATH（gitea-mcp init 写入的就是这种配置）：

{
  "mcpServers": {
    "gitea": {
      "command": "uvx",
      "args": ["gitea-mcp"],
      "env": {
        "GITEA_URL": "https://your-gitea-instance.example.com",
        "GITEA_TOKEN": "your-personal-access-token"
      }
    }
  }
}

如果你更愿意使用通过 pip 全局安装的 gitea-mcp 二进制文件，可以移除 args，并将 command 直接设为 "gitea-mcp"——只要启动时该二进制文件位于 MCP 客户端的 PATH 中，就能正常使用。

完整示例见 mcp.json。相同的配置格式也适用于 Claude Desktop、VS Code、Cowork、Claude Code，以及任何其他兼容 MCP 的客户端。

配置

配置通过环境变量读取。

变量	必填	默认值	描述
GITEA_URL	是	—	Gitea 实例的基础 URL（例如，https://gitea.example.com）
GITEA_TOKEN	是	—	在 Gitea 用户设置中生成的个人访问令牌
GITEA_TIMEOUT	否	30	HTTP 请求超时时间，单位为秒
GITEA_MAX_RETRIES	否	3	对幂等方法（GET/PUT/DELETE）发生暂时性故障时的最大重试次数。设为 0 可禁用重试。POST 和 PATCH 不会自动重试，因为它们可能创建重复的问题、评论或发行版。对于任何方法，都会重试 429 Too Many Requests，并在存在 Retry-After 时遵循该值。
GITEA_RETRY_BASE_DELAY	否	0.5	重试之间指数退避的基础延迟时间（秒）。实际延迟按 base * 2^attempt 增长，并加入随机抖动，最多为 4 秒。

自托管 / HTTP 传输

默认情况下，gitea-mcp 以 stdio 模式运行——每个 MCP 客户端（Claude Desktop、Cowork 等）都会按需启动自己的子进程。若要自托管一个实例，供多个客户端通过网络连接，请使用流式 HTTP 传输：

gitea-mcp serve --transport http --host 0.0.0.0 --port 8000 --path /mcp

这四个标志也可以通过环境变量提供（适用于 Docker / systemd 单元）：

变量	默认值	标志
GITEA_MCP_TRANSPORT	stdio	--transport
GITEA_MCP_HOST	127.0.0.1	--host
GITEA_MCP_PORT	8000	--port
GITEA_MCP_PATH	/mcp	--path

MCP 客户端连接到生成的 URL（例如 https://gitea-mcp.example.com/mcp），方式与连接本地 stdio 服务相同，只是多个客户端共享同一个运行中的实例。

身份验证模式（此版本）。 服务会从自身环境中读取 GITEA_TOKEN，因此任何能够访问该 URL 的客户端都会以同一个 Gitea 用户的身份操作。请在自己的访问控制措施（防火墙、反向代理身份验证、VPN、Tailscale）后为自己运行此服务。支持多租户自带令牌已列入路线图。

不带参数的调用（不带子命令的 gitea-mcp）仍以 stdio 模式运行，因此现有的 Claude Desktop / Cowork / Claude Code 集成不受此项新增功能影响。

兼容性

服务	状态
Gitea（自托管）	✅ 主要目标
Forgejo	✅ 预计可用（API 兼容）
Codeberg	✅ 预计可用（Codeberg 运行 Forgejo）

开发

git clone https://github.com/werebear73/gitea-mcp.git
cd gitea-mcp
pip install -e ".[dev]"
pre-commit install                       # commit-stage hooks (ruff + mypy)
pre-commit install --hook-type pre-push  # push-stage hooks (pytest + build check)
pytest

两阶段的提交前策略既能让提交流程保持轻快（仅运行 lint + 类型检查），又能让 git push 在耗时较长的检查通过后才继续。这些检查包括完整测试套件和 python -m build && twine check dist/*，后者曾在过去发现过 CI / 发布故障，可在 setuptools_scm 的版本意外情况进入标签推送前将其暴露出来。

路线图

请参阅 docs/ROADMAP.md，了解已发布内容、后续计划和范围之外的事项。

发布

• MCP Registry 元数据记录在 server.json 中。
• Smithery 和 MCP Registry 的发布步骤记录在 docs/PUBLISHING.md 中。

版本管理

采用语义化版本管理，通过 setuptools_scm 从 git 标签派生版本。请参阅 VERSIONING.md，了解发布流程。

贡献

欢迎提交问题和拉取请求。如需进行重大更改，请先提交问题，讨论实现方案。

许可证

MIT — 你可以随意使用，包括用于商业产品。

---

由 Waretech Services 构建。