HomeWork/gitea-mcp
5
0
Fork 0
mirror of https://gitea.com/gitea/gitea-mcp.git synced 2026-08-03 07:39:22 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: rewrite the tool tables and slim down the READMEs (#215)

Browse Source 
Fixes https://gitea.com/gitea/gitea-mcp/issues/214.

The tool tables listed tools that had not existed for several releases. They are regenerated from the registry, gain an `Access` column so it is visible what disappears under `-r` / `GITEA_READONLY`, and get their fine-grained scopes back. `TestReadmeToolTables` now compares them against the registry in both directions, for every translation.

Other corrections from verifying the prose against the source: the pagination parameter is `per_page`, not `perPage`; Go 1.26 is required, not 1.24; the Chinese READMEs were missing the OpenCode and Mistral Vibe sections.

Also trimmed the drifted table of contents and the sections the intro and `gitea-mcp --help` already cover, and dropped the heading emoji. `CLAUDE.md` had its own stale tool list, so it now points at `AGENTS.md` like gitea/gitea does.

---------

Co-authored-by: silverwind <me@silverwind.io>
Reviewed-on: https://gitea.com/gitea/gitea-mcp/pulls/215
Reviewed-by: silverwind <2021+silverwind@noreply.gitea.com>
This commit is contained in:
Lunny Xiao
2026-07-23 17:08:19 +00:00
parent b1a6ed9f6b
commit 18fcd663e0
8 changed files with 391 additions and 666 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.zh-cn.md
+102 -171
View File
@@ -2,40 +2,27 @@
[English](README.md) | [繁體中文](README.zh-tw.md)
**Gitea MCP 服务器** 是一个集成插件，旨在将 Gitea 与 Model Context Protocol (MCP) 系统连接起来。这允许通过 MCP 兼容的聊天界面无缝执行命令和管理仓库。
**Gitea MCP 服务器** 将 [Gitea](https://about.gitea.com) 实例接入 [Model Context Protocol](https://modelcontextprotocol.io) 客户端，让仓库、问题、拉取请求等都能在兼容 MCP 的聊天界面中浏览和管理。
[![在 VS Code 中使用 Docker 安装](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=gitea&inputs=[{%22id%22:%22gitea_token%22,%22type%22:%22promptString%22,%22description%22:%22Gitea%20Personal%20Access%20Token%22,%22password%22:true}]&config={%22command%22:%22docker%22,%22args%22:[%22run%22,%22-i%22,%22--rm%22,%22-e%22,%22GITEA_ACCESS_TOKEN%22,%22docker.gitea.com/gitea-mcp-server%22],%22env%22:{%22GITEA_ACCESS_TOKEN%22:%22${input:gitea_token}%22}}) [![在 VS Code Insiders 中使用 Docker 安装](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=gitea&inputs=[{%22id%22:%22gitea_token%22,%22type%22:%22promptString%22,%22description%22:%22Gitea%20Personal%20Access%20Token%22,%22password%22:true}]&config={%22command%22:%22docker%22,%22args%22:[%22run%22,%22-i%22,%22--rm%22,%22-e%22,%22GITEA_ACCESS_TOKEN%22,%22docker.gitea.com/gitea-mcp-server%22],%22env%22:{%22GITEA_ACCESS_TOKEN%22:%22${input:gitea_token}%22}}&quality=insiders)
## 目录
## 安装
- [Gitea MCP 服务器](#gitea-mcp-服务器)
- [目录](#目录)
- [什么是 Gitea？](#什么是-gitea)
- [什么是 MCP？](#什么是-mcp)
- [🚧 安装](#-安装)
- [在 Claude Code 中使用](#在-claude-code-中使用)
- [在 VS Code 中使用](#在-vs-code-中使用)
- [📥 下载官方二进制版本](#-下载官方二进制版本)
- [🔧 从源码构建](#-从源码构建)
- [📁 加入 PATH](#-加入-path)
- [🚀 使用](#-使用)
- [✅ 可用工具](#-可用工具)
- [🐛 调试](#-调试)
- [🛠 疑难排解](#-疑难排解)
可从 [发布页面](https://gitea.com/gitea/gitea-mcp/releases) 下载二进制文件并放入 `PATH`，或使用 `docker.gitea.com/gitea-mcp-server` 镜像，也可用 `make` 和 Go 1.26 及以上从源码构建到 `$GOPATH/bin`：
## 什么是 Gitea？
```bash
git clone https://gitea.com/gitea/gitea-mcp.git
cd gitea-mcp
make install
```
Gitea 是一个由社区管理的轻量级代码托管解决方案，使用 Go 语言编写，采用 MIT 许可证。Gitea 提供 Git 托管，包括仓库浏览、问题追踪、拉取请求等功能。
## 配置
## 什么是 MCP？
Gitea 主机和访问令牌可通过命令行参数或环境变量提供，命令行参数优先。运行 `gitea-mcp --help` 可查看完整的参数与环境变量列表。日志写入 `$HOME/.gitea-mcp/gitea-mcp.log`，加上 `-d` 可启用调试日志。
Model Context Protocol (MCP) 是一种协议，允许通过聊天界面整合各种工具和系统。它能够无缝执行命令并管理仓库、用户及其他资源。
### Claude Code
## 🚧 安装
### 在 Claude Code 中使用
此方式使用 `go run`，需要安装 [Go](https://go.dev)。
通过 `go run` 运行服务器，需要安装 [Go](https://go.dev)：
```bash
claude mcp add --transport stdio --scope user gitea \
@@ -44,15 +31,9 @@ claude mcp add --transport stdio --scope user gitea \
-- go run gitea.com/gitea/gitea-mcp@latest -t stdio
```
### 在 VS Code 中使用
### VS Code
要快速安装，请使用本 README 顶部的安装按钮。
如需手动安装，请将以下 JSON 块添加到 VS Code 的用户设置 (JSON) 文件。可通过按 `Ctrl + Shift + P` 并输入 `Preferences: Open User Settings (JSON)`。
也可添加到工作区的 `.vscode/mcp.json` 文件，方便与他人共享配置。
> `.vscode/mcp.json` 文件不需要 `mcp` 键。
可使用本 README 顶部的安装按钮，或将下面的内容加入用户设置 (JSON)，按 `Ctrl + Shift + P` 并输入 `Preferences: Open User Settings (JSON)` 即可打开。也可放在工作区的 `.vscode/mcp.json` 中，此时无需 `mcp` 键。
```json
{
@@ -68,14 +49,7 @@ claude mcp add --transport stdio --scope user gitea \
"servers": {
"gitea-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITEA_ACCESS_TOKEN",
"docker.gitea.com/gitea-mcp-server"
],
"args": ["run", "-i", "--rm", "-e", "GITEA_ACCESS_TOKEN", "docker.gitea.com/gitea-mcp-server"],
"env": {
"GITEA_ACCESS_TOKEN": "${input:gitea_token}"
}
@@ -85,59 +59,50 @@ claude mcp add --transport stdio --scope user gitea \
}
```
### 📥 下载官方二进制版本
### OpenCode
可在 [官方 Gitea MCP 二进制版本](https://gitea.com/gitea/gitea-mcp/releases) 下载。
将下面的内容加入 [OpenCode](https://opencode.ai) 配置的顶层 `mcp` 对象：
### 🔧 从源码构建
可用 Git 下载源码：
```bash
git clone https://gitea.com/gitea/gitea-mcp.git
```json
"gitea-mcp": {
"enabled": true,
"type": "local",
"command": [
"gitea-mcp",
"-t", "stdio",
"-H", "https://gitea.com",
"-T", "<your personal access token>"
]
}
```
构建前请先安装：
### Mistral Vibe
- make
- Golang（建议 Go 1.24 及以上）
将下面的内容加入 `~/.vibe/config.toml`：
然后运行：
```toml
[[mcp_servers]]
name = "gitea"
transport = "stdio"
command = "docker"
args = ["run", "--rm", "-i", "-e", "GITEA_ACCESS_TOKEN", "-e", "GITEA_HOST", "docker.gitea.com/gitea-mcp-server"]
```bash
make install
[mcp_servers.env]
GITEA_ACCESS_TOKEN = "TOKEN"
GITEA_HOST = "https://gitea.com"
```
### 📁 加入 PATH
### 其他客户端
安装后，将 gitea-mcp 可执行文件复制到系统 PATH 目录，例如：
```bash
cp gitea-mcp /usr/local/bin/
```
## 🚀 使用
此示例适用于 Cursor，也可在 VSCode 使用插件。
要配置 Gitea MCP 服务器，请将以下内容添加到 MCP 配置文件：
- **stdio 模式**
Cursor 等客户端可使用 stdio 命令：
```json
{
"mcpServers": {
"gitea": {
"command": "gitea-mcp",
"args": [
"-t",
"stdio",
"--host",
"https://gitea.com"
// "--token", "<your personal access token>"
],
"args": ["-t", "stdio", "--host", "https://gitea.com"],
"env": {
// "GITEA_HOST": "https://gitea.com",
// "GITEA_INSECURE": "true",
"GITEA_ACCESS_TOKEN": "<your personal access token>"
}
}
@@ -145,7 +110,7 @@ cp gitea-mcp /usr/local/bin/
}
```
- **http 模式**
或使用 http 端点，对应以 `gitea-mcp -t http --port 8080` 启动的服务器：
```json
{
@@ -160,100 +125,66 @@ cp gitea-mcp /usr/local/bin/
}
```
**默认日志路径**: `$HOME/.gitea-mcp/gitea-mcp.log`
配置完成后，可在聊天框输入 `列出我所有的仓库` 试试。
> [!注意]
> 可通过命令行参数或环境变量提供 Gitea 主机和访问令牌。
> 命令行参数优先。
## 可用工具
> [!注意]
> 许多工具支持 `page` 和 `perPage` 分页参数。最大有效页面大小由 Gitea 服务器的 `[api].MAX_RESPONSE_ITEMS` 设置决定（默认值：**50**）。请求超过此限制的 `perPage` 值将被服务器静默截断。
| 工具 | 范围 | 访问 | 描述 |
| :--------------------------- | :------- | :--- | :------------------------------------------------------------------- |
| get_gitea_mcp_server_version | 版本 | 读取 | 获取 Gitea MCP 服务器版本 |
| get_me | 用户 | 读取 | 获取当前已认证用户 |
| get_user_orgs | 用户 | 读取 | 列出当前用户的组织 |
| search_users | 搜索 | 读取 | 搜索用户 |
| search_org_teams | 搜索 | 读取 | 搜索组织中的团队 |
| search_repos | 搜索 | 读取 | 搜索仓库 |
| search_issues | 搜索 | 读取 | 跨仓库搜索问题和拉取请求 |
| notification_read | 通知 | 读取 | 读取通知：列出（可限定仓库）或按 ID 获取会话 |
| notification_write | 通知 | 写入 | 将某条或全部通知标记为已读 |
| label_read | 标签 | 读取 | 读取仓库或组织标签 |
| label_write | 标签 | 写入 | 写入标签（仓库或组织）：创建、编辑、删除 |
| milestone_read | 里程碑 | 读取 | 读取里程碑：获取单个或列出 |
| milestone_write | 里程碑 | 写入 | 写入里程碑：创建、更新、删除 |
| wiki_read | Wiki | 读取 | 读取 Wiki：列出页面、获取内容、修订历史 |
| wiki_write | Wiki | 写入 | 写入 Wiki 页面：创建、更新、删除 |
| timetracking_read | 时间跟踪 | 读取 | 读取时间跟踪：问题/仓库耗时、活动计时器、我的跟踪记录 |
| timetracking_write | 时间跟踪 | 写入 | 写入时间跟踪：计时器和记录条目 |
| package_read | 软件包 | 读取 | 读取软件包注册表：列出软件包、列出版本或获取某个版本 |
| package_write | 软件包 | 写入 | 删除软件包版本（不可恢复） |
| list_issues | 问题 | 读取 | 列出仓库问题 |
| issue_read | 问题 | 读取 | 读取问题：详情、评论或标签 |
| issue_write | 问题 | 写入 | 写入问题：创建、更新、管理评论和标签 |
| list_pull_requests | 拉取请求 | 读取 | 列出仓库拉取请求 |
| pull_request_read | 拉取请求 | 读取 | 读取拉取请求：详情、差异、变更文件、头部提交状态、审查 |
| pull_request_write | 拉取请求 | 写入 | 写入拉取请求：创建、更新、关闭、重新打开、合并、更新分支、管理审查者 |
| pull_request_review_write | 拉取请求 | 写入 | 写入 PR 审查：创建、提交、删除、驳回 |
| actions_config_read | Actions | 读取 | 读取 Actions 密钥和变量 |
| actions_config_write | Actions | 写入 | 写入 Actions 密钥和变量：更新插入、创建、更新、删除 |
| actions_run_read | Actions | 读取 | 读取 Actions 工作流、运行、作业、日志和构件 |
| actions_run_write | Actions | 写入 | 写入 Actions 运行：触发、取消、重新运行 |
| create_repo | 仓库 | 写入 | 创建新仓库 |
| fork_repo | 仓库 | 写入 | 复刻仓库 |
| list_my_repos | 仓库 | 读取 | 列出当前用户拥有的仓库 |
| list_org_repos | 仓库 | 读取 | 列出组织中的仓库 |
| get_repository_tree | 仓库 | 读取 | 获取仓库文件树 |
| get_file_contents | 文件 | 读取 | 获取文件内容和元数据 |
| get_dir_contents | 文件 | 读取 | 获取目录中的条目 |
| create_or_update_file | 文件 | 写入 | 创建或更新文件（提供 sha 以更新现有文件） |
| delete_file | 文件 | 写入 | 删除文件 |
| create_branch | 分支 | 写入 | 创建新分支 |
| delete_branch | 分支 | 写入 | 删除分支 |
| list_branches | 分支 | 读取 | 列出仓库分支 |
| create_tag | Git 标签 | 写入 | 创建标签 |
| delete_tag | Git 标签 | 写入 | 删除标签 |
| get_tag | Git 标签 | 读取 | 获取标签详情 |
| list_tags | Git 标签 | 读取 | 列出仓库标签 |
| list_commits | 提交 | 读取 | 列出仓库提交 |
| get_commit | 提交 | 读取 | 获取提交详情 |
| create_release | 版本发布 | 写入 | 创建版本发布 |
| delete_release | 版本发布 | 写入 | 删除版本发布 |
| get_release | 版本发布 | 读取 | 按 ID 获取版本发布 |
| get_latest_release | 版本发布 | 读取 | 获取最新版本发布 |
| list_releases | 版本发布 | 读取 | 列出仓库版本发布 |
一切设置完成后，可在 MCP 聊天框输入：
> **说明：** 部分工具是聚合的、基于操作的工具，单个工具通过 `method` 参数暴露多个操作。当服务器以只读模式运行时（`-r` / `GITEA_READONLY`），访问为「写入」的工具会被隐藏；可通过 `-O` / `--tools`（`GITEA_TOOLS`）过滤对外暴露的工具集合。
```text
列出我所有的仓库
```
## ✅ 可用工具
Gitea MCP 服务器支持以下工具：
| 工具 | 范围 | 描述 |
| :-------------------------------: | :------: | :------------------------: |
| get_my_user_info | 用户 | 获取已认证用户信息 |
| get_user_orgs | 用户 | 获取已认证用户关联组织 |
| create_repo | 仓库 | 创建新仓库 |
| fork_repo | 仓库 | 复刻仓库 |
| list_my_repos | 仓库 | 列出用户所有仓库 |
| create_branch | 分支 | 创建新分支 |
| delete_branch | 分支 | 删除分支 |
| list_branches | 分支 | 列出所有分支 |
| create_release | 版本发布 | 创建新版本发布 |
| delete_release | 版本发布 | 删除版本发布 |
| get_release | 版本发布 | 获取版本发布 |
| get_latest_release | 版本发布 | 获取最新版本发布 |
| list_releases | 版本发布 | 列出所有版本发布 |
| create_tag | 标签 | 创建新标签 |
| delete_tag | 标签 | 删除标签 |
| get_tag | 标签 | 获取标签 |
| list_tags | 标签 | 列出所有标签 |
| list_repo_commits | 提交 | 列出所有提交 |
| get_file_content | 文件 | 获取文件内容和元数据 |
| get_dir_content | 文件 | 获取目录内容列表 |
| create_file | 文件 | 创建新文件 |
| update_file | 文件 | 更新现有文件 |
| delete_file | 文件 | 删除文件 |
| get_issue_by_index | 问题 | 按索引获取问题 |
| list_repo_issues | 问题 | 列出所有问题 |
| create_issue | 问题 | 创建新问题 |
| create_issue_comment | 问题 | 在问题上创建评论 |
| edit_issue | 问题 | 编辑问题 |
| edit_issue_comment | 问题 | 编辑问题评论 |
| get_issue_comments_by_index | 问题 | 按索引获取问题评论 |
| get_pull_request_by_index | 拉取请求 | 按索引获取拉取请求 |
| list_repo_pull_requests | 拉取请求 | 列出所有拉取请求 |
| create_pull_request | 拉取请求 | 创建新拉取请求 |
| create_pull_request_reviewer | 拉取请求 | 为拉取请求添加审查者 |
| delete_pull_request_reviewer | 拉取请求 | 移除拉取请求的审查者 |
| list_pull_request_reviews | 拉取请求 | 列出拉取请求的所有审查 |
| get_pull_request_review | 拉取请求 | 按 ID 获取特定审查 |
| list_pull_request_review_comments | 拉取请求 | 列出审查的行内评论 |
| create_pull_request_review | 拉取请求 | 创建审查（可含行内评论） |
| submit_pull_request_review | 拉取请求 | 提交待处理的审查 |
| delete_pull_request_review | 拉取请求 | 删除审查 |
| dismiss_pull_request_review | 拉取请求 | 驳回审查（可附消息） |
| merge_pull_request | 拉取请求 | 合并拉取请求 |
| search_users | 用户 | 搜索用户 |
| search_org_teams | 组织 | 搜索组织团队 |
| list_org_labels | 组织 | 列出组织标签 |
| create_org_label | 组织 | 创建组织标签 |
| edit_org_label | 组织 | 编辑组织标签 |
| delete_org_label | 组织 | 删除组织标签 |
| search_repos | 仓库 | 搜索仓库 |
| get_gitea_mcp_server_version | 服务器 | 获取 Gitea MCP 服务器版本 |
| list_wiki_pages | Wiki | 列出所有 Wiki 页面 |
| get_wiki_page | Wiki | 获取 Wiki 页面内容和元数据 |
| get_wiki_revisions | Wiki | 获取 Wiki 修订历史 |
| create_wiki_page | Wiki | 创建新 Wiki 页面 |
| update_wiki_page | Wiki | 更新现有 Wiki 页面 |
| delete_wiki_page | Wiki | 删除 Wiki 页面 |
## 🐛 调试
启用调试模式时，请在 http 模式运行 Gitea MCP 服务器时加上 `-d` 标志：
```sh
./gitea-mcp -t http [--port 8080] --token <your personal access token> -d
```
## 🛠 疑难排解
如遇问题，可参考以下步骤：
1. **检查 PATH**：确保 `gitea-mcp` 可执行文件已在系统 PATH 目录中。
2. **验证依赖**：确认已安装 `make` 和 `Golang` 等必要依赖。
3. **检查配置**：仔细检查 MCP 配置文件是否有错误或遗漏。
4. **查看日志**：检查日志消息或警告以获取更多信息。
享受通过聊天探索和管理您的 Gitea 仓库！
许多工具支持 `page` 和 `per_page` 分页参数。最大有效页面大小由 Gitea 服务器的 `[api].MAX_RESPONSE_ITEMS` 设置决定（默认 **50**），超出的值会被静默截断。