MCP 被比喻成“AI 世界的 USB-C”：接口统一，即插即用。如果你的代码托管在自建 Gitea 上，现在多了一个官方选项——gitea-mcp，Gitea 官方自己维护的 MCP 服务器。装好之后，Cursor、Claude、VS Code 这类客户端就能用自然语言翻仓库、建分支、提 PR、回 Issue，不用再手点网页。

但网上多数教程停在“能跑”：下载、填个 token、重启客户端，完事。真正用起来，坑都在后头——有人去 GitHub 搜仓库，装回的是一堆第三方同名项目；有人把全权限令牌直接交给 AI；有人开着 HTTP 模式裸奔；还有人被分页悄悄截断，批量操作漏了一半数据。这篇基于 v1.8.1（2026 年 10 月 9 日发布）把安装、配置、使用到注意事项一次讲完。

01 它是什么，以及一个入口误区

MCP（Model Context Protocol）是一套开放协议，给 AI 应用接入工具和数据源定标准，官方教程把它比作“AI 世界的 USB-C”。gitea-mcp 就是这套标准下的 Gitea 官方实现：把 Gitea 的 API 封装成一个个 MCP 工具，让兼容客户端用对话的方式浏览和管理仓库、Issue、PR 和 Release。项目采用 MIT 协议，源码完全开放。

什么样的团队值得上车？代码托管在自建 Gitea、对数据敏感、又想让 AI 进入日常工作流的——这三条占一条，就值得花半小时试一遍。反过来，如果仓库都在 SaaS 上，各家官方集成更成熟，未必需要再自建这一层。

第一个坑在入口。官方仓库不在 GitHub，而在 Gitea 自家实例：

官方仓库只在 gitea.com/gitea/gitea-mcp；GitHub 上搜到的 gitea-mcp 几乎都是第三方同名实现（社区里有 Node/TypeScript 版本），工具列表、配置项和官方版并不一致，混着看只会越配越晕。

版本现状先钉一下：最新稳定版为 v1.8.1，发布于 2026 年 10 月 9 日。从 v1.8.0 起，project_read 和 project_write 两个工具要求 Gitea 服务端版本在 v28 或更高，老服务器用不了这两个工具。能力边界上，服务器只广播 tools 一种能力（不提供 resources 和 prompts），协议版本支持到 2026-07-28，启动时与客户端协商降到客户端版本。

02 安装：三条路，按场景选

官方给了三条安装路径：个人本地用优先选二进制，常驻服务用 Docker，想读源码或追主线再考虑编译。

选二进制的话，按平台对号入座（包名以 v1.8.1 为例）：

Releases 页同时提供 i386 与 Windows arm64 包，并附 checksums.txt。稳妥做法是下载后先把安装包的 SHA256 值与 checksums.txt 里的记录逐一比对，对不上就重新下载，不要解压。Windows 用户解压后，把 gitea-mcp.exe 所在目录加入 PATH，新开一个终端，能跑通 gitea-mcp --help 即安装成功。

源码编译就三条命令：git clone https://gitea.com/gitea/gitea-mcp.git，然后 cd gitea-mcp，再 make install。Go 版本要求有两个官方口径并存：仓库 README 当前写的是 1.27 或更高，官方教程页还挂着 1.24 以上的旧说法，动手前以代码库 go.mod 为准最保险。

03 配置：令牌、参数与传输模式

第一步拿令牌：登录你的 Gitea 实例，进入 Settings → Applications，生成新的 access token。令牌等同于密码，别提交进 git，别贴进聊天记录；一旦泄露，立刻去后台吊销重发。

传参有两条通道：命令行 flags 优先，环境变量兜底。核心环境变量如下：

常用 flags 一览，完整列表以 gitea-mcp --help 输出为准：

日志默认写在 $HOME/.gitea-mcp/gitea-mcp.log，排错先看它，嫌信息不够就加 -d。

补两个传参细节。其一，命令行 flags 优先于环境变量：同一参数两处都给了，以命令行为准。其二，令牌走 -T 会留在 shell 历史和进程列表里，敏感场景优先用环境变量，或者直接上 GITEA_ACCESS_TOKEN_FILE 读文件——Docker 环境下接 secret 正合适。

第一次接入的建议姿势：先只读。以 -r 加上 stdio 模式跑几天，让 AI 只能查、不能写，确认它选工具和填参数的路数符合预期，再按需放权。这一步能避开大多数“AI 比你想的更能干”的惊吓。

传输模式按客户端位置选：本地客户端（Claude Code、Cursor、VS Code）用 stdio，配置简单、稳定性好；要把一个服务器共享给多个客户端或部署在远端，用 HTTP 模式。HTTP 有几个硬事实要先知道：/mcp 端点只收 POST；服务完全无状态，没有会话 ID，也不支持 SSE 流式恢复；客户端凭证通过 Authorization 头透传（Bearer 或 token 两种前缀均可），逐请求交给 Gitea——这是凭证透传，不是 MCP OAuth；被 Gitea 拒绝的凭证会返回 401，客户端可借此刷新。HTTP 模式另提供 /healthz 健康探针，Kubernetes 的 httpGet 可以直接用。

04 接进客户端：四个官方样例

Claude Code 一条命令搞定，服务器通过 go run 启动，需要本机装有 Go：

claude mcp add --transport stdio --scope user gitea --env GITEA_ACCESS_TOKEN=your-token --env GITEA_HOST=https://gitea.com -- go run gitea.com/gitea/gitea-mcp@latest -t stdio

VS Code 改用户设置 JSON（按 Ctrl+Shift+P，输入并选择 Preferences: Open User Settings (JSON)），也可以放工作区的 .vscode/mcp.json——后者要省略最外层 mcp 键。官方样例用 inputs 让令牌以密码方式输入，服务进程用 docker run 拉镜像；把 command 和 args 换成本地二进制路径同样成立。

Cursor 用户有更省事的走法：Settings → MCP → Add Server，粘贴配置后显示绿色即连通；README 顶部还内置了 VS Code 的一键安装按钮，点一下自动写配置。各家的客户端支持清单，可以在 modelcontextprotocol.io/clients 查。

Cursor 等通用客户端改 mcpServers 配置即可，stdio 与 HTTP 两种写法都列在这：

// stdio mode {   "mcpServers": {     "gitea": {       "command": "gitea-mcp",       "args": ["-t", "stdio", "--host", "https://gitea.com"],       "env": { "GITEA_ACCESS_TOKEN": "your-token" }     }   } }  // http mode {   "mcpServers": {     "gitea": {       "url": "http://localhost:8080/mcp",       "headers": { "Authorization": "Bearer your-token" }     }   } }

HTTP 写法的前提，是先用 gitea-mcp -t http --port 8080 把服务器拉起来。另外两个客户端顺带一提：OpenCode 在顶层 mcp 对象里加一条 type 为 local 的 command 配置；Mistral Vibe 则编辑 ~/.vibe/config.toml，加一段 [[mcp_servers]]。

全部配置完成后的统一验证动作：在聊天框发一句 “list all my repositories”，能列出你的仓库，链路即通。

05 工具全景与使用方式

工具按 scope 分组，每个 scope 下分读、写两类。主要 scope 一张表看完：

其余 scope——user、notification、label、milestone、wiki、timetracking、packages、project——同样是读写配对，其中 project 系列需要 Gitea v28 以上；version scope 只有一个 get_gitea_mcp_server_version，用来确认服务器版本。

使用层面有三个要点。其一，不少工具是合并式设计：一个工具通过 method 参数暴露多个操作，工具数量比预期少是正常的。其二，分页有隐形天花板：很多工具接受 page 和 per_page，但有效页大小上限是 Gitea 服务端的 [api].MAX_RESPONSE_ITEMS 配置，默认 50，要得更大会被静默截断——批量场景老老实实翻页。其三，错误分两层：工具自身或 Gitea 侧的失败，返回的是带 result.isError: true 的工具结果；请求格式错误和服务器故障才是 JSON-RPC error，排错时先分清层级。

具体用起来就是正常说话：“帮我在 owner/repo 上从 feature 分支提一个 PR 到 main”，“列一下这个仓库还没关的 Issue”，“把 README 的安装章节更新一下”。选工具、填参数这些活儿由 AI 自己完成，你负责在关键动作前把好最后一关。

还有一条实践建议：读的活（查 Issue、读 diff、总结 commit 历史）尽量交给 AI，写的活（合并 PR、删分支、删包版本）保留人工确认。MCP 客户端一般带工具调用确认弹窗，别为了省事全程点允许。

06 注意事项：九个坑挨个排

把最容易翻车的地方浓缩成九条，按危险程度大致排序：

• 装错仓库。
  官方仓库只在 gitea.com/gitea/gitea-mcp，GitHub 上没有；第三方同名项目的文档别混着看。
• 令牌权限过大。
  先用 -r 只读跑通全流程，再按需扩权；最小权限是底线。
• 版本兼容两件事。
  project 系列工具要 Gitea v28 以上；协议版本 2026-07-28 会向下协商，但客户端太老可能直接连不上，先升级客户端。
• HTTP 模式别裸奔。
  必须套 HTTPS；反向代理要原样转发 Mcp-Protocol-Version、Mcp-Method、Mcp-Name 三个头，Host 也别乱改——/mcp 只认 -oauth-public-url 或 loopback 主机名。
• 远程客户端走 OAuth，别图省事共用静态令牌。
  Claude.ai 网页和移动端这类拿不到 token 的客户端，用 -oauth 搭配 -oauth-public-url 启动；提前在 Gitea 的 Settings → Applications 注册 OAuth2 应用，不勾 Confidential Client（走 PKCE），重定向 URI 按客户端填——Claude 系填 https://claude.ai/api/mcp/auth_callback，Claude Code 再加一个 http://127.0.0.1/callback；服务器和 Gitea 都要对客户端网络 HTTPS 可达。
• 分页截断是静默的。
  别以为拉到了底，批量操作循环翻页，并用总数类工具抽查。
• package_write 删除包版本不可逆。
  动手前让 AI 把它要删的版本名列出来给你确认。
• Docker 健康检查有隐藏条件。
  只读根文件系统下必须给 /tmp 挂 tmpfs，否则探针失败。
• 排障按顺序来。
  先看日志 $HOME/.gitea-mcp/gitea-mcp.log（不够就加 -d），再分清 isError（工具层）和 JSON-RPC error（协议层），最后去官方 Issues 页搜同类问题。

最后一句实在话：生产环境上手前，拿一个测试仓库把这九个坑完整踩一遍，是成本最低的演练。

结语

MCP 服务器这一波，拼的不是谁家工具多，而是谁把“AI 操作代码托管”做成了标准接口。Gitea 官方亲自下场，意味着自建代码托管也能无缝接进 AI 工作流——对数据敏感、又想尝 AI 提效的团队，这条路现在通了。

接下来值得盯两件事：一是工具覆盖还在扩，v1.8.0 刚补上 project 系列；二是它和 Gitea Actions 的联动——等 CI 状态、工作流分发都能用对话聊出来，“对话即运维”就不远了。

💬 聊聊你的看法

你的代码托管在哪——自建 Gitea、GitHub 还是别的？如果让 AI 直接给你的仓库开分支、提 PR，你敢放手到哪一步？

📌 数据来源说明

• Gitea 官方仓库 gitea-mcp 的 README 与 Releases 页（gitea.com/gitea/gitea-mcp，2026-10-15 访问；版本口径以 v1.8.1 为准）
• Gitea 官方教程《Gitea MCP Server: A New Paradigm for AI-Driven Code Collaboration》（about.gitea.com，2026-10-15 访问）
• 版本兼容说明摘自 v1.8.0 Release Notes 与仓库 README（Gitea v28+、协议 2026-07-28、Go 版本双口径）

⚠️ 免责声明

本文为资讯分析类内容，所有数据均来自公开渠道并经人工交叉核实，仅供参考，不构成任何投资建议或技术决策依据。操作生产环境仓库前，请先在测试环境验证，并遵循最小权限原则。文中涉及的机构名称、产品名称、商标归各自所有者所有。本文由 AI 辅助撰写。