Lean Github Mcp

---

这是什么？

这是一个 Model Context Protocol（MCP） 服务，可将 Claude 直接连接到 GitHub API。安装后，你可以通过自然对话管理整个 GitHub 工作流 — 无需图形界面、无需复制粘贴 URL，也无需切换上下文。

你可以在 Claude 中这样输入：

Merge PR #47 with squash, delete the branch, then create a release v2.1.0 with those changes

Claude 会完成所有操作。 调用三次 API，即可完成。

---

为什么选择它，而不是官方 GitHub MCP？

	此服务	官方 GitHub MCP
设置	npm install + 令牌	需要 Docker
响应大小	平均约 320 个令牌	2000+ 个令牌（原始 API）
令牌效率	移除空值、精简内容	原始 JSON 直通
缓存	120s 内存缓存	无缓存
工具	19 个工具	约 30 个工具
默认分支	自动检测	硬编码为 main
错误消息	包含状态码	通用消息
许可证	MIT — 可在任何地方使用	MIT

总而言之： 此服务专为精简而构建。每个响应都会移除空值、智能截断，并在适当时进行缓存。我们将 Claude 的上下文窗口视为宝贵资源。

---

60 秒完成设置

选项 1 — 使用 npx 运行（无需安装）：

GITHUB_TOKEN=ghp_your_token npx @noushad999/lean-github-mcp

选项 2 — 从 npm 全局安装：

npm install -g @noushad999/lean-github-mcp
lean-github-mcp

选项 3 — Docker (即将推出)：

docker run -e GITHUB_TOKEN=ghp_your_token ghcr.io/noushad999/lean-github-mcp

选项 4 — 从源代码克隆：

git clone https://github.com/noushad999/lean-github-mcp.git
cd lean-github-mcp
npm install && npm run build
echo "GITHUB_TOKEN=ghp_your_token" > .env

Claude Desktop — 编辑 %APPDATA%\Claude\claude_desktop_config.json（Windows）或 ~/Library/Application Support/Claude/claude_desktop_config.json（Mac）：

使用 npx（最简单 — 无需安装）：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@noushad999/lean-github-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

使用本地构建：

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["C:/absolute/path/to/lean-github-mcp/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Claude Code（命令行）：

claude mcp add github -- node /absolute/path/to/lean-github-mcp/dist/index.js

重启 Claude，即可完成。

---

所需的令牌权限

前往 github.com/settings/tokens?type=beta → Fine-grained token：

权限	级别	使用方
Contents	读写	get_file、create_branch、delete_branch
Issues	读写	list_issues、create_issue、assign_issue、add_comment
Pull requests	读写	list_prs、create_pr、merge_pr、get_pr_diff
Actions	读写	list_workflows、trigger_workflow
Metadata	读取	list_repos、get_repo

---

可用工具

仓库

list_repos

列出任意用户或组织的仓库。

"Show me all of vercel's public repos sorted by recent activity"

参数	类型	必填	默认值
owner	string	是	—
type	owner | member	否	owner

---

get_repo

获取指定仓库的详细统计信息。

"Tell me about facebook/react — stars, forks, language, open issues"

参数	类型	必填
owner	string	是
repo	string	是

---

议题

list_issues

列出带有标签和受指派人的议题。

"Show all open bugs in my repo"

参数	类型	必填	默认值
owner	string	是	—
repo	string	是	—
state	open | closed | all	否	open

---

create_issue

创建带有标签的新议题。

"Create an issue titled 'Login crashes on Safari' with labels bug and priority"

参数	类型	必填
owner	string	是
repo	string	是
title	string	是
body	string	否
labels	string[]	否

---

assign_issue

为议题或 PR 添加或移除受指派人。

"Assign issue #42 to alice and bob"

参数	类型	必填	默认值
owner	string	是	—
repo	string	是	—
issue_number	number	是	—
assignees	string[]	是	—
action	add | remove	否	add

---

拉取请求

list_prs

按状态列出拉取请求。

"What PRs are currently open in vercel/next.js?"

参数	类型	必填	默认值
owner	string	是	—
repo	string	是	—
state	open | closed | all	否	open

---

create_pr

创建拉取请求。如果省略 base，则自动检测仓库的默认分支。

"Create a PR from feat/dark-mode to main titled 'Add dark mode support'"

参数	类型	必填	默认值
owner	string	是	—
repo	string	是	—
title	string	是	—
body	string	否	—
head	string	是	—
base	string	否	仓库默认值

---

get_pr_diff

获取拉取请求的统一差异内容，最多 200 行。

"Show me the diff for PR #88"

参数	类型	必填
owner	string	是
repo	string	是
pull_number	number	是

---

merge_pr

使用你选择的策略合并。

"Squash-merge PR #47 with title 'feat: dark mode'"

参数	类型	必填	默认值
owner	string	是	—
repo	string	是	—
pull_number	number	是	—
method	merge | squash | rebase	否	merge
commit_title	string	否	—

---

分支

create_branch

从任意基准创建分支。自动检测默认分支。

"Create branch fix/header-overflow from main"

参数	类型	必填	默认值
owner	string	是	—
repo	string	是	—
branch	string	是	—
base	string	否	仓库默认值

---

delete_branch

删除分支，通常在合并后执行。

"Delete the feat/dark-mode branch, it's been merged"

参数	类型	必填
owner	string	是
repo	string	是
branch	string	是

---

提交与文件

list_commits

查看近期提交历史记录，包括作者和时间戳。

"Show the last 5 commits on the main branch"

参数	类型	必填	默认值
owner	string	是	—
repo	string	是	—
branch	string	否	仓库默认值
per_page	1–10	否	10

---

get_file

从任意分支读取文件内容。超过 100 行的文件会被截断。

"Show me the contents of src/auth.ts on the dev branch"

参数	类型	必填	默认值
owner	string	是	—
repo	string	是	—
path	string	是	—
branch	string	否	仓库默认值

---

search_code

在整个 GitHub 上搜索代码。

"Find all TypeScript files using useAuth hook"

参数	类型	必填	默认值
query	string	是	—
per_page	1–10	否	10

GitHub 的代码搜索 API 需要身份验证，且速率限制约为每分钟 10 次请求。结果会缓存 120 秒。

---

评论

add_comment

在任意议题或拉取请求中发表评论。

"Add a comment to PR #55 saying the deployment is ready for testing"

参数	类型	必填
owner	string	是
repo	string	是
issue_number	number	是
body	string	是

---

发布版本

get_release

获取最新发布版本，或查询特定标签。

"What's the latest release of vercel/next.js?"

参数	类型	必填	默认值
owner	string	是	—
repo	string	是	—
tag	string	否	最新

---

create_release

发布包含发行说明的新版本。

"Create release v2.1.0 on the main branch with the changelog I'll paste"

参数	类型	必填	默认值
owner	string	是	—
repo	string	是	—
tag_name	string	是	—
name	string	否	标签名称
body	string	否	—
draft	boolean	否	false
prerelease	boolean	否	false
target_commitish	string	否	仓库默认值

---

GitHub Actions

list_workflows

列出仓库中的所有工作流。

"What GitHub Actions workflows does this repo have?"

参数	类型	必填
owner	string	是
repo	string	是

---

trigger_workflow

触发工作流分发事件，并可选择提供输入。

"Trigger the deploy.yml workflow on the staging branch"

参数	类型	必填	默认值
owner	string	是	—
repo	string	是	—
workflow_id	string | number	是	—
ref	string	否	仓库默认值
inputs	object	否	{}

---

工作原理

You (natural language)
        │
        ▼
   Claude AI
        │  MCP Protocol (stdio)
        ▼
┌──────────────────────────────────┐
│        lean-github-mcp           │
│                                  │
│  ┌─────────────────────────┐     │
│  │   19 Tool Handlers      │     │
│  └────────┬────────────────┘     │
│           │                      │
│  ┌────────▼─────┐  ┌──────────┐  │
│  │  Token Guard │  │  Cache   │  │
│  │  4000 char   │  │  120s    │  │
│  │  null strip  │  │  200 max │  │
│  └────────┬─────┘  └────┬─────┘  │
│           └──────┬───────┘        │
│                  ▼                │
│      ┌──────────────────┐         │
│      │  GitHub Client   │         │
│      │  Axios + Auth    │         │
│      │  Status codes    │         │
│      └──────────────────┘         │
└──────────────┬───────────────────┘
               │ HTTPS
               ▼
        api.github.com

Token 效率——为何重要

MCP 服务发送的每条响应都会占用你的 Claude 上下文窗口。响应内容臃肿，会让 Claude 更快忘记对话的前面内容。此服务会积极精简响应：

单个仓库的原始 GitHub API 响应：

{
  "id": 1296269,
  "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
  "name": "Hello-World",
  "full_name": "octocat/Hello-World",
  "private": false,
  "owner": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://api.github.com/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "...",
    ... 20 more owner fields
  },
  "html_url": "https://github.com/octocat/Hello-World",
  "description": "This your first repo!",
  ... 80+ more fields, mostly null
}

约 2,400 个 token

此服务的响应：

{
  "name": "Hello-World",
  "full_name": "octocat/Hello-World",
  "description": "This your first repo!",
  "stars": 2045,
  "forks": 1731,
  "language": "JavaScript",
  "open_issues": 12,
  "updated_at": "2024-01-15T10:30:00Z",
  "html_url": "https://github.com/octocat/Hello-World"
}

约 90 个 token——小 26 倍

---

真实对话示例

完整的 PR 工作流：

You: Show me open PRs in my-org/my-repo

Claude: Found 3 open PRs:
  #88 — "Add OAuth2 support" by sarah_dev
  #91 — "Fix memory leak in worker" by john_k
  #94 — "Upgrade to Node 22" by bot

You: Show me the diff for #91

Claude: [shows unified diff of the memory leak fix]

You: Looks good. Merge it with squash, then delete the branch

Claude: Done — squash merged PR #91 (sha: a3f9c21), deleted branch fix/memory-leak

You: Now create a release v3.2.1 from main with changelog: "Fixed memory leak in background workers"

Claude: Release v3.2.1 published — https://github.com/my-org/my-repo/releases/tag/v3.2.1

四项独立的 GitHub 操作。一段对话。

---

自动化分流：

You: List open issues in my-org/api-server, assign the ones labeled "bug" to me

Claude: Found 4 open issues. 2 have the "bug" label (#34, #41).
  Assigned #34 and #41 to you.

---

测试

npm run build
npx tsx tests/simulate-10-users.ts

预期输出：

╔══════════════════════════════════════════════════════════╗
║     GitHub MCP Server - 10 User Deployment Test        ║
║          19 Tools · Full Coverage Simulation           ║
╚══════════════════════════════════════════════════════════╝
...
║  Total Tests:        49                  ║
║  Passed:             49                  ║
║  Failed:             0                   ║
║  Pass Rate:          100.0          %    ║
║  Null Fields Found:  0                   ║
║  Avg Response:       319            tokens ║
╚══════════════════════════════════════════╝
🎉 ALL TESTS PASSED! Ready for production.

你也可以使用 MCP Inspector 检查实时状态：

npx @modelcontextprotocol/inspector node dist/index.js

---

项目结构

lean-github-mcp/
├── src/
│   ├── index.ts                  # MCP server entry, tool registration
│   ├── github-client.ts          # Axios client + getDefaultBranch helper
│   ├── middleware/
│   │   └── tokenGuard.ts         # Response trimmer: null strip, compactify, 4000 char limit
│   ├── utils/
│   │   └── cache.ts              # 120s TTL in-memory cache, max 200 entries
│   └── tools/                    # 19 tool handlers (one file each)
│       ├── list_repos.ts
│       ├── get_repo.ts
│       ├── list_issues.ts
│       ├── create_issue.ts
│       ├── assign_issue.ts
│       ├── list_prs.ts
│       ├── create_pr.ts
│       ├── get_pr_diff.ts
│       ├── merge_pr.ts
│       ├── create_branch.ts
│       ├── delete_branch.ts
│       ├── list_commits.ts
│       ├── get_file.ts
│       ├── search_code.ts
│       ├── add_comment.ts
│       ├── get_release.ts
│       ├── create_release.ts
│       ├── list_workflows.ts
│       └── trigger_workflow.ts
├── tests/
│   └── simulate-10-users.ts      # Full simulation test, 49 assertions
├── dist/                         # Compiled JS (after npm run build)
├── package.json
├── tsconfig.json
└── .env.example

---

故障排除

GITHUB_TOKEN not set

cat .env    # make sure GITHUB_TOKEN=ghp_... is there

GitHub API (403): Rate limited or insufficient permissions

• 精细粒度令牌需要明确授予仓库访问权限——请检查上方的权限表
• 代码搜索的速率限制更严格（约 10 次请求/分钟）——等待 60 秒后重试

GitHub API (404): Resource not found

• 仔细检查 owner 和 repo 的拼写
• 访问私有仓库需要令牌具有相应权限

GitHub API (422): Unprocessable

• 通常表示该分支已存在 PR，或分支名称无效

Claude Desktop 中出现 Command not found: node

• 使用完整路径：C:\Program Files\nodejs\node.exe（Windows），或在 Mac/Linux 上运行 which node

---

贡献

欢迎贡献——请参阅 CONTRIBUTING.md，了解添加新工具的分步指南、代码规范和 PR 检查清单。

---

路线图

• list_workflow_runs — 查看分支的 CI 状态
• get_commit — 查看单个提交的详细信息及变更文件
• compare_branches — 对比两个分支的差异
• update_file — 直接提交文件变更
• add_label / remove_label — 管理标签

如有希望添加的功能，请提交 issue。

---

许可证

MIT——你可以随意使用。

---