内容
<p align="center">
<img alt="gitea-mcp" src="https://raw.githubusercontent.com/amonstack/gitea_mcp/master/docs/assets/gitea-mcp-banner.png" />
<h3 align="center">gitea-mcp</h3>
<p align="center">MCP 服务器，暴露 Gitea 问题、标签、里程碑、评论和主题，作为 AI 助手的工具</p>
</p>
---
[](https://www.npmjs.com/package/@amonstack/gitea-mcp)
[](https://codecov.io/gh/amonstack/gitea_mcp)
[](https://github.com/amonstack/gitea_mcp/blob/master/LICENSE)
[](https://www.npmjs.com/package/@amonstack/gitea-mcp)
[](https://www.typescriptlang.org)
[](https://modelcontextprotocol.io)
**中文文档** | [English](https://github.com/amonstack/gitea_mcp/blob/master/README.md)
`gitea-mcp` 是一个 [模型上下文协议（MCP）](https://modelcontextprotocol.io/) 服务器，暴露 Gitea 仓库操作作为工具。一旦连接到 MCP 客户端（Claude Desktop、opencode、Cursor 等），AI 助手就可以通过自然语言列出、创建、更新和删除 Gitea 实例上的问题、标签、里程碑、评论和主题。
服务器通过 stdio 通信，并包装 [Gitea REST API（/api/v1）](https://docs.gitea.com/api/1.22/)。
## 功能
- **完整的 Gitea 项目管理** — 通过自然语言管理问题、标签、里程碑、评论和主题
- **零配置自动发现** — 从项目的 git 配置中读取 `baseUrl`、`owner`、`repo` 和令牌；一个全局安装服务多个仓库
- **多源身份验证和故障转移** — 尝试 `[gitea]` 配置令牌、`GITEA_TOKEN`，然后是 git 凭证存储，在 `401`/`403` 上自动推进
- **作用域技能** — 为 opencode、Claude Code、Cursor 等提供每个工作流的技能（查找、创建、标记、评论、计划里程碑等）
- **客户端无关** — 与任何基于 stdio 的 MCP 客户端一起使用；还提供指导提示和按需参考资源
## 目录
- [功能](#功能)
- [需求](#需求)
- [安装](#安装)
- [配置](#配置)
- [MCP 客户端设置](#mcp-客户端设置)
- [可用工具](#可用工具)
- [AI 指导和技能](#ai-指导和技能)
- [开发](#开发)
- [贡献](#贡献)
- [许可证](#许可证)
## 需求
- **Node.js ≥ 24** — 使用全局 `fetch`
- 一个 **Gitea 实例**（自托管或 Gitea Cloud），可以通过 HTTP 访问
- 一个 **Gitea API 令牌**（或 git 凭证存储条目），用于读取公共仓库以外的任何内容
## 安装
### 从 npm（npmjs.com）
```bash
npm install -g @amonstack/gitea-mcp
```
或直接运行而无需全局安装：
```bash
npx @amonstack/gitea-mcp
```
### 从 GitHub Packages
每个版本也会发布到 GitHub Packages。路由到那里 `@amonstack` 范围，然后安装：
```bash
echo "@amonstack:registry=https://npm.pkg.github.com" >> ~/.npmrc
npm install -g @amonstack/gitea-mcp
```
### 从源码构建
```bash
git clone https://github.com/amonstack/gitea-mcp.git
cd gitea-mcp
npm ci
npm run build
node dist/cli.js
```
## 配置
所有变量都是可选的 — `gitea-mcp` 从项目的本地 git 配置中自动发现 Gitea 实例、仓库和令牌，因此单个全局安装可以服务多个项目。仅在需要覆盖发现时设置它们。
| 变量 | 必需 | 描述 |
| --- | --- | --- |
| `GITEA_BASE_URL` | 否 | Gitea 实例 URL（例如 `https://gitea.example.com`）。省略时从项目的 git remote 自动检测。 |
| `GITEA_TOKEN` | 否 | Gitea API 访问令牌。多个身份验证候选人之一；在 `.git/config [gitea]` 令牌和 git 凭证存储（见 [令牌发现](#令牌发现)）之后尝试。 |
| `GITEA_DEFAULT_OWNER` | 否 | 默认仓库所有者 — 跳过在每次调用时传递 `owner` |
| `GITEA_DEFAULT_REPO` | 否 | 默认仓库名称 — 跳过在每次调用时传递 `repo` |
### 自动发现如何工作
启动时，`gitea-mcp` 读取 `<cwd>/.git/config` 并派生：
- **实例 URL** — 从选定的远程主机的 host。SSH remotes（`git@host:owner/repo`）解析为 `https://host`。使用 `GITEA_BASE_URL` 覆盖。
- **所有者/仓库** — 从选定的远程 URL。 使用 `GITEA_DEFAULT_OWNER` / `GITEA_DEFAULT_REPO` 覆盖，或使用 `resolve_repo` 工具临时检测。
- **远程选择** — 优先使用 `upstream` 远程，然后是 `origin`，然后是其他远程。`resolve_repo` 在它们不同的情况下都会报告。
如果当前目录没有 git remote 且未设置 `GITEA_BASE_URL`，服务器不会启动 — 它会打印跳过原因并退出 0。在克隆的 Gitea 仓库中运行它，或显式设置 `GITEA_BASE_URL` / `GITEA_TOKEN`。
### 令牌发现
`gitea-mcp` 从三个来源收集身份验证 **候选人**，按此优先级顺序：
1. `.git/config` 中的 `[gitea "<baseUrl>"]` 部分（裸 `[gitea]` 部分是主机范围的后备）：
```ini
[gitea "https://gitea.example.com"]
token = <your-token>
```
始终作为 `Authorization: token <token>` 发送。
2. `GITEA_TOKEN` 环境变量 — 也作为 `Authorization: token` 发送。
3. git 凭证存储（`~/.git-credentials` 或 `$XDG_CONFIG_HOME/git/credentials`）— 匹配实例的每个行，例如 `https://alice:s3cret@gitea.example.com`。当多个行匹配时，路径与 `owner/repo` 匹配最好的行优先尝试。
凭证存储条目的 `password` 字段可能包含真正的 PAT、帐户密码或 OAuth 令牌 — git 存储用户在提示符下输入的内容，服务器无法静态区分它们。因此，每个凭证存储条目都在 **两种身份验证方案** 下尝试：
- `Authorization: Basic <base64(user:pass)>` — 适用于帐户密码和 PAT（Gitea 检查用户名与密钥的所有者是否匹配）。
- `Authorization: token <secret>` — 仅适用于真正的 PAT。
顺序由用户名启发式选择：约定用户名（`oauth2`、`x-oauth-basic` 或空）首先尝试 `token`；类似真实的用户名（例如 `alice`）首先尝试 `basic`。
**容错性。** 在 `401`/`403` 时，服务器会推进到下一个方案/候选人并重试相同的请求；一旦组合成功，它就会锁定整个会话（不会重新探测）。非身份验证错误（`404`、`500`、网络）会立即传播，不会触发重试。
**诊断。** `gitea_status` 工具（见 [仓库助手](#仓库助手)）返回当前状态的删节视图 — 哪个候选人处于活动状态，哪些候选人已用完，最后看到的错误（删节；永远不会暴露密钥）。使用它来排查 `401` 而不是猜测。
如果没有来源解析凭证，服务器仍然会匿名启动。公共仓库可以读取；私有仓库和写入操作会返回 `401` — 使用 `gitea-configure` 技能引导设置，或设置 `GITEA_TOKEN`。
当设置 `GITEA_DEFAULT_OWNER` 和 `GITEA_DEFAULT_REPO` 时，可以省略工具调用中的 `owner` 和 `repo` 参数。`resolve_repo` 工具也可以从本地 git 仓库自动检测它们。
## MCP 客户端设置
### Claude Desktop
添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"gitea-mcp": {
"command": "gitea-mcp",
"env": {
"GITEA_BASE_URL": "https://gitea.example.com",
"GITEA_TOKEN": "your-token-here",
"GITEA_DEFAULT_OWNER": "my-org",
"GITEA_DEFAULT_REPO": "my-repo"
}
}
}
}
```
如果您从源码构建，请使用 `node /path/to/gitea-mcp/dist/cli.js` 代替。
### opencode
添加到您的 opencode MCP 配置：
```json
{
"mcpServers": {
"gitea-mcp": {
"command": "gitea-mcp",
"env": {
"GITEA_BASE_URL": "https://gitea.example.com",
"GITEA_TOKEN": "your-token-here"
}
}
}
}
```
如果您从源码构建，请使用 `node /path/to/gitea-mcp/dist/cli.js` 代替。
opencode 和其他 AI 工具可以加载原生 **技能** — 每个操作一个（查找、创建、更新、标记、评论、总结、计划里程碑、解析仓库）— 教导助手最安全的该操作工作流，包括使用前检查和陷阱。使用 `init` 命令安装它们，针对您的工具（ `--tool`，默认为 `opencode`）：
```bash
gitea-mcp init # opencode (全局 ~/.config/opencode/skills/)
gitea-mcp init --tool claude # Claude Code (~/.claude/skills/)
gitea-mcp init --tool cursor # Cursor (~/.cursor/skills/)
gitea-mcp init --project # 此项目 (./.<tool>/skills/)
gitea-mcp init --dir /exact/path # 自定义位置
```
支持的 `--tool` 值：`amazon-q`、`antigravity`、`auggie`、`claude`、`cline`、`codex`、`codebuddy`、`continue`、`costrict`、`crush`、`cursor`、`factory`、`gemini`、`github-copilot`、`iflow`、`kilocode`、`opencode`、`qoder`、`qwen`、`roocode`、`windsurf`。路径遵循每个工具的约定技能目录；使用 `--dir` 获取确切位置。然后重启您的工具。参见 [AI 指导和技能](#ai-指导和技能)。
### 其他 MCP 客户端
任何支持基于 stdio 的 MCP 服务器的客户端都可以使用 `gitea-mcp`。安装后，从克隆的 Gitea 仓库内部运行它（自动发现配置）：
```bash
cd /path/to/your/gitea-repo
gitea-mcp
```
或显式设置变量：
```bash
export GITEA_BASE_URL="https://gitea.example.com"
export GITEA_TOKEN="your-access-token"
gitea-mcp
```
## 可用工具
### 问题
| 工具 | 描述 |
| --- | --- |
| `list_issues` | 列出问题（按 `state`、`labels`、`page/limit` 筛选） |
| `get_issue` | 按索引（问题编号）获取单个问题 |
| `create_issue` | 创建具有 `title`、`body`、`assignee`、`labels`、`milestone` 的问题 |
| `update_issue` | 更新问题字段或 `state` |
| `delete_issue` | 按索引删除问题 |
| `search_issues` | 跨仓库按 `query`、`type`、`state`、`labels` 搜索 |
### 评论
| 工具 | 描述 |
| --- | --- |
| `list_comments` | 列出问题上的评论 |
| `create_comment` | 添加评论到问题 |
| `update_comment` | 更新评论的 `id` |
| `delete_comment` | 按 `id` 删除评论 |
### 标签
| 工具 | 描述 |
| --- | --- |
| `list_labels` | 列出仓库标签 |
| `create_label` | 创建标签（`name`、`color`、`description`） |
| `update_label` | 更新标签的 `id` |
| `delete_label` | 按 `id` 删除标签 |
| `add_issue_labels` | 为问题添加标签名称 |
| `remove_issue_label` | 从问题中删除标签 `id` |
| `replace_issue_labels` | 替换问题上的所有标签 |
| `clear_issue_labels` | 从问题中删除所有标签 |
### 里程碑
| 工具 | 描述 |
| --- | --- |
| `list_milestones` | 列出里程碑（按 `state` 筛选） |
| `get_milestone` | 按 `id` 获取里程碑 |
| `create_milestone` | 创建具有 `title`、`description`、`due_on` 的里程碑 |
| `update_milestone` | 更新里程碑字段或 `state` |
| `delete_milestone` | 按 `id` 删除里程碑 |
### 主题
| 工具 | 描述 |
| --- | --- |
| `list_topics` | 列出仓库的主题（标签） |
| `replace_topics` | 用给定的列表替换所有主题（传递 `[]` 清空） |
| `add_topic` | 按名称添加单个主题 |
| `remove_topic` | 按名称删除单个主题 |
### 仓库助手
| 工具 | 描述 |
| --- | --- |
| `list_my_repos` | 列出身份验证用户可访问的仓库 |
| `resolve_repo` | 从项目的 git remotes 检测 `baseUrl`、`owner` 和 `repo`（优先使用 `upstream`，然后是 `origin`） |
| `gitea_status` | 检查凭证处理状态 — 活动候选人、已用完候选人、最后错误（删节；永远不会暴露密钥） |
## AI 指导和技能
服务器提供指导，以便助手正确、安全地使用工具，通过三个渠道：
- **`instructions`（连接时）** — 服务器在 MCP 握手期间发送的简洁策略；有能力的客户端会自动将其注入系统提示中。
- **工具描述** — 每个工具的描述都会标记其关键风险（分页、标签 ID 与名称、破坏范围）和最小用法示例。
- **提示和资源** — 工作流模板（`triage_issues`、`summarize_issue`、`audit_labels`、`milestone_report`）和按需参考文档（字段参考、标签指南、工具烹饪书）适用于支持它们的客户端。
### 操作技能
对于 opencode 和其他工具，服务器提供一组 **作用域技能** — 每个工作流一个，因此助手仅加载所需的指导（永远不会，例如，在创建时删除）。使用上面的 `gitea-mcp init --tool <name>` 命令安装它们。
| 技能 | 调用时机 |
| --- | --- |
| `gitea-find-issues` | 发现 / 读取 / 分类问题 |
| `gitea-create-issue` | 创建问题（在检查重复后） |
| `gitea-update-issue` | 编辑字段、关闭、清除指派/里程碑 |
| `gitea-label-issue` | 在问题上添加 / 替换 / 删除 / 清除标签 |
| `gitea-manage-labels` | 创建或编辑标签定义 |
| `gitea-comment-issue` | 发布推进问题讨论的评论 |
| `gitea-summarize-issue` | 读取和总结问题的讨论 |
| `gitea-plan-milestones` | 创建 / 编辑 / 关闭里程碑 |
| `gitea-resolve-repo` | 解析所有者/仓库或列出仓库 |
| `gitea-configure` | 修复连接 — 实例 URL、令牌或 401/403 错误 |
每个技能都是一个简短的 AI 面向动作流程（目的、何时使用、何时不使用、规则以及首先检查的内容）。创建、评论和里程碑技能还嵌入 **正文模板**（问题、评论、里程碑），这些模板标准化了助手的书写内容。破坏性单工具动作（删除问题 / 评论 / 标签 / 里程碑）故意留给工具描述，以免污染创造性工作流。
## 开发
```bash
git clone https://github.com/amonstack/gitea-mcp.git
cd gitea-mcp
npm ci
```
| 命令 | 描述 |
| --- | --- |
| `make lint` | 仅类型检查 |
| `make build` | 编译 `src/` 到 `dist/` |
| `make test` | 运行单元测试 |
| `make test-watch` | 在监视模式下运行测试 |
| `make test-integration` | 运行集成测试（需要实时 Gitea 实例） |
| `make scan` | 使用 gitleaks 扫描泄露的密钥（`make verify` 的一部分） |
| `make dev` | 直接使用 tsx 运行 |
有关完整的架构 — 模块布局、依赖图、核心模式以及添加新工具的指南，请参见 [`docs/architecture.md`](docs/architecture.md)。
## 贡献
欢迎贡献！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 以了解有关报告错误、建议功能和提交拉取请求指南。
## 许可证
[MIT](LICENSE) — Copyright (c) 2026 [amonstack](https://github.com/amonstack)。
