GitHub Explorer MCP

GitHub Explorer MCP

为 Claude Desktop、Cursor 等 MCP 客户端提供 GitHub 仓库信息的 MCP 服务，包括文件内容、目录结构及其他元数据。

功能

• 仓库摘要：获取 GitHub 仓库的全面信息
• 目录结构：通过清晰的 ASCII 树形图查看任意仓库的完整文件结构
• 文件内容：访问特定文件的内容
• 元数据增强：获取星标数、分叉数、描述和最近更新时间
• 本地仓库克隆：在本地克隆仓库，以加快处理速度并获取更完整的数据
• 缓存系统：高效缓存仓库数据，减少 API 调用
• 进度通知：获取长时间运行操作的更新
• 格式选项：以文本或结构化 JSON 格式获取数据
• 自动补全：获取仓库所有者和名称的建议
• Web 界面：以 HTTP 模式运行时提供基本状态页面和信息

安装

使用 NPM

# Install from npm
npm install @trishchuk/github-explorer-mcp -g

# Run the server (stdio mode for MCP clients)
github-explorer-mcp

# Or run in HTTP/SSE mode
github-explorer-mcp-sse

使用 Docker

# Build Docker image
docker build -t github-explorer-mcp .

# Run container
docker run -p 3000:3000 github-explorer-mcp

在 MCP 客户端中使用

Claude Desktop

添加到 Claude Desktop 配置中：

{
  "mcpServers": {
    "github-explorer": {
      "command": "npx",
      "args": ["-y", "@trishchuk/github-explorer-mcp"]
    }
  }
}

Cursor

添加到 Cursor 配置中：

{
  "mcpServers": {
    "github-explorer": {
      "command": "npx",
      "args": ["-y", "@trishchuk/github-explorer-mcp"]
    }
  }
}

API 参考

MCP 服务提供以下工具：

github_repository_summary

获取 GitHub 仓库的摘要。

{
  owner: string;    // GitHub organization or username
  repo: string;     // Repository name
  branch?: string;  // Optional branch name
  includeMetadata?: boolean; // Include stars, forks, etc.
}

github_directory_structure

获取 GitHub 仓库的树形结构。

{
  owner: string;    // GitHub organization or username
  repo: string;     // Repository name
  branch?: string;  // Optional branch name
}

github_read_important_files

获取 GitHub 仓库中特定文件的内容。

{
  owner: string;     // GitHub organization or username
  repo: string;      // Repository name
  filePaths: string[]; // List of paths to files
  branch?: string;   // Optional branch name
  format?: 'text' | 'json'; // Output format
}

git_search（即将推出）

搜索 GitHub 仓库中的内容。

{
  owner: string;     // GitHub organization or username
  repo: string;      // Repository name
  query: string;     // Search query
  branch?: string;   // Optional branch name
  maxResults?: number; // Maximum results to return
}

git_diff（即将推出）

获取两个分支或提交之间的差异。

{
  owner: string;     // GitHub organization or username
  repo: string;      // Repository name
  base: string;      // Base branch/commit
  head: string;      // Head branch/commit
}

开发

# Clone the repository
git clone https://github.com/x51xxx/github-explorer-mcp.git
cd github-explorer-mcp

# Install dependencies
npm install

# IMPORTANT: This project requires Node.js 18 or later
# If using nvm, run:
nvm use

# Build the project
npm run build

# Run the built server
npm start
# or
npm run start:sse

故障排除

Node.js 版本问题

本项目需要 Node.js 18 或更高版本，因为它使用了 ReadableStream 等现代 Web API。如果遇到如下错误：

ReferenceError: ReadableStream is not defined

请执行以下操作：

1. 将 Node.js 更新至 18 或更高版本
2. 如果使用 nvm，请在项目目录中运行 nvm use
3. 确保使用包含必要 polyfill 的修改版脚本

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

MIT