gitx-mcp

适用于Gitea和Forgejo实例的MCP服务器，针对AI代理进行了优化。提供43个工具，涵盖问题、拉取请求、文件、分支、提交、标签、里程碑、发布、通知、维基、组织、用户和CI/CD操作。

安装

需要锈 1.75+.

从git仓库安装：

cargo install --git https://github.com/0xErgod/gitx-mcp.git

或者克隆并在本地构建：

git clone https://github.com/0xErgod/gitx-mcp.git
cd gitx-mcp
cargo install --path .

二进制文件安装到 ~/.cargo/bin/gitx-mcp.

配置

gitx mcp需要两个环境变量：

变量	描述
`GITEA_URL`	Gitea/Forgejo实例的基本URL（例如。 `https://git.example.com`)
`GITEA_TOKEN`	具有适当权限的API令牌

为了向后兼容性， FORGEJO_REMOTE_URL 和 FORGEJO_AUTH_TOKEN 也被接受。

生成API令牌

转到您的Gitea/Forgejo实例
引导到 设置>应用程序>访问令牌
创建一个具有所需作用域的令牌（例如。 repo, issue, admin:org)

使用Claude代码进行设置

在Claude Code设置中添加gitx-mcp作为mcp服务器。您可以在项目级别或全局配置它。

项目级设置

创建或编辑 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "gitx-mcp": {
      "command": "gitx-mcp",
      "env": {
        "GITEA_URL": "https://your-gitea-instance.com",
        "GITEA_TOKEN": "your-api-token-here"
      }
    }
  }
}

全局设置

增添 ~/.claude/settings.json （或使用 /mcp 克劳德代码）：

{
  "mcpServers": {
    "gitx-mcp": {
      "command": "gitx-mcp",
      "env": {
        "GITEA_URL": "https://your-gitea-instance.com",
        "GITEA_TOKEN": "your-api-token-here"
      }
    }
  }
}

使用.env文件

或者，创建一个 .env 工作目录中的文件（请参见 .env.example):

GITEA_URL=https://your-gitea-instance.com
GITEA_TOKEN=your-api-token-here

那么MCP配置只需要：

{
  "mcpServers": {
    "gitx-mcp": {
      "command": "gitx-mcp"
    }
  }
}

存储库解析

大多数工具都接受 owner 和 repo 用于标识目标存储库的参数。这些可以省略——gitx-mcp按以下顺序解析存储库：

明确的 owner + repo --当两者都提供时，总是优先考虑
directory 参数 --自动检测 .git/config 在给定的目录中
自动检测到默认值 --启动时，服务器读取 .git/config 从工作目录中获取结果，并将其作为MCP资源公开(repo://detected)
CWD回退 --解析 .git/config 在通话时从当前目录中

这 repo://detected 资源回报 {"owner": "...", "repo": "..."} 并列在 resources/list 当检测到存储库时。MCP客户端可以读取它以确认服务器正在哪个存储库上运行。

工具

问题（4个工具）

工具	说明
`issue_list`	在存储库中列出问题。按状态（打开/关闭）和标签过滤。
`issue_get`	获取特定问题的完整详细信息，包括正文、标签、受让人和里程碑。
`issue_create`	创建一个包含标题、正文、标签、里程碑和指定人员的新问题。
`issue_edit`	更新问题的标题、正文、状态、标签、受让人或里程碑。

问题评论（2个工具）

工具	说明
`issue_comment_list`	列出对特定问题或拉取请求的所有评论。
`issue_comment_create`	向现有问题或拉取请求添加注释。

拉取请求（5个工具）

工具	说明
`pr_list`	在存储库中列出拉取请求。按状态过滤（打开/关闭/全部）。
`pr_get`	获取完整的PR详细信息，包括分支机构、可合并状态、标签和受让人。
`pr_create`	使用head/base分支、title、body和标签创建新的pull请求。
`pr_edit`	更新PR的标题、正文、状态、标签或受让人。
`pr_merge`	使用合并、重基或挤压策略合并拉取请求。

拉取请求评论（2个工具）

工具	说明
`pr_review_list`	在pull请求中列出带有审阅者、状态和正文的审阅。
`pr_review_create`	提交评论：批准、请求_更改或评论。

拉取请求文件（2个工具）

工具	说明
`pr_files`	列出PR中已更改的文件及其状态和差异统计信息。
`pr_diff`	获取拉取请求中所有更改的原始统一差异。

文件（6个工具）

工具	说明
`file_read`	读取特定参考处的文件内容返回路径、大小、SHA和内容。
`file_list`	在路径（单目录级别）中列出文件和目录。
`file_create`	使用提交创建一个新文件。内容是纯文本（自动base64编码）。
`file_update`	更新现有文件。需要SHA `file_read`.
`file_delete`	删除文件。需要SHA `file_read`.
`tree_get`	获取存储库的完整递归文件树。

分支（5个工具）

工具	说明
`branch_list`	列出所有具有最新提交SHA和保护状态的分支。
`branch_create`	从现有分支创建新分支或提交SHA。
`branch_delete`	删除分支。
`branch_protection_list`	列出分支保护规则。
`branch_protection_create`	使用推送和查看设置创建分支保护规则。

提交（4个工具）

工具	说明
`commit_list`	列表提交，可选择按分支/标签或文件路径过滤。
`commit_get`	获取完整的提交详细信息，包括差异统计数据和父提交。
`commit_diff`	获取特定提交的原始统一差异。
`commit_compare`	比较两个引用，查看它们之间的提交和更改的文件。

标签（3个工具）

工具	说明
`label_list`	列出所有带有ID、名称、颜色和描述的标签。
`label_create`	使用名称和十六进制颜色创建新标签。
`label_edit`	更新标签的名称、颜色或描述。

里程碑（3个工具）

工具	说明
`milestone_list`	列出具有ID、标题、状态和问题计数的里程碑。
`milestone_get`	获取完整的里程碑详细信息，包括描述和截止日期。
`milestone_create`	创建一个带有标题、描述和截止日期的新里程碑。

通知（2个工具）

工具	说明
`notification_list`	列出您的通知，包括主题、类型和阅读状态。
`notification_mark_read`	将所有或特定通知标记为已读。

发布（3个工具）

工具	说明
`release_list`	列出带有标签名称、标题和草稿/预发布标志的发布。
`release_get`	获取完整的发布详细信息，包括正文和资产。
`release_create`	使用标签、标题和发行说明创建新版本。

存储库（2个工具）

工具	说明
`repo_get`	获取存储库元数据：描述、默认分支、星型、分支、可见性。
`repo_search`	在Gitea实例中按关键字搜索存储库。

用户（2个工具）

工具	说明
`user_get_me`	获取经过身份验证的用户的个人资料（用户名、电子邮件、管理员状态）。
`user_get`	按用户名获取用户的公开个人资料。

标签（2个工具）

工具	说明
`tag_list`	列出所有带有名称的标签并提交SHA。
`tag_create`	创建一个指向提交或分支的新标记。

Wiki（3个工具）

工具	说明
`wiki_list`	列出带有标题和slug的wiki页面。
`wiki_get`	按标题阅读维基页面的内容。
`wiki_create`	创建一个带有标题和标记内容的新维基页面。

组织（3个工具）

工具	说明
`org_list`	列出经过身份验证的用户所属的组织
`org_get`	按名称获取组织详细信息。
`org_teams`	列出组织中具有权限的团队。

行动/CI（4个工具）

工具	说明
`actions_workflow_list`	列出存储库中配置的CI/CD工作流。
`actions_run_list`	列出工作流运行状态和结论。
`actions_run_get`	获取特定工作流运行的详细信息。
`actions_job_logs`	获取特定CI/CD作业的日志以进行调试。

关键工作流程

更新或删除文件

总是打电话 file_read 首先获取当前文件SHA，然后将其传递给 file_update 或 file_delete:

file_read(path: "README.md") -> SHA: "abc123..."
file_update(path: "README.md", sha: "abc123...", content: "...", message: "update readme")

分配标签或里程碑

标签和里程碑使用数字ID，而不是名称。首先查找ID：

label_list() -> [{id: 1, name: "bug"}, {id: 2, name: "enhancement"}]
issue_create(title: "Fix login", labels: [1])

合并拉取请求

合并前检查PR是否可合并：

pr_get(index: 42) -> mergeable: true
pr_merge(index: 42, merge_style: "squash")

释放

此项目使用释放plz 用于本地版本碰撞和更改日志生成。不需要CI/CD。

安装发布plz

cargo install release-plz --locked

工作流程

# Preview what would change (dry run)
release-plz update --dry-run

# Bump version in Cargo.toml and update CHANGELOG.md
release-plz update

# Review, commit, and tag
git add -A && git commit -m "chore: release v$(grep '^version' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')"
release-plz release

release-plz update 读取自上次git标签以来的常规提交，确定适当的semver缓冲区，更新 Cargo.toml，并将条目添加到 CHANGELOG.md. release-plz release 创建a vX.Y.Z git标签。

配置存在于 release-plz.toml.

许可证

麻省理工学院

gitx MCP

快速接入

详细介绍