GitHub Crawler MCP

GitHub仓库爬虫MCP服务器

一个强大的模型上下文协议（MCP）服务器，使ChatGPT和其他AI助手能够抓取GitHub存储库并与之交互，包括公共和私有存储库。内置于 FastMCP.

特性

🔍 全面的GitHub API集成 -10个用于存储库探索的专用工具：

• 搜索存储库 通过高级过滤查询
• 获取存储库详细信息 包括星号、叉号、主题和许可证
• 列出用户/组织存储库 具有排序选项
• 浏览存储库内容 -文件和目录
• 获取完整的存储库结构 像一棵树
• 阅读README文件 以markdown格式
• 列表提交 包含作者和消息详细信息
• 分析编程语言 在存储库中使用
• 浏览问题 带状态过滤
• 下载文件内容 具有自动解码功能

🔐 私有存储库访问 -完全支持使用GitHub个人访问令牌的私有存储库

⚡ 高利率限制 -有身份验证时每小时5000个请求（没有身份验证时为60个）

🚀 轻松部署 -部署到FastMCP Cloud并直接连接到ChatGPT

安装

1.克隆或创建项目

mkdir github-crawler-mcp
cd github-crawler-mcp

放置 github_crawler_server.py 此目录中的文件。

2.安装依赖项

pip install -r requirements.txt

这将安装：

• fastmcp -MCP服务器框架
• httpx -GitHub API的异步HTTP客户端
• python-dotenv -环境变量管理

3.配置GitHub Token

创建一个 .env 项目根目录中的文件：

cp .env.example .env

编辑 .env 并添加您的GitHub个人访问令牌：

GITHUB_TOKEN=ghp_your_actual_token_here

创建GitHub个人访问令牌：

1. 首选https://github.com/settings/tokens
2. 点击 “生成新令牌（经典）”
3. 给它一个描述性的名称（例如，“MCP GitHub Crawler”）
4. 选择范围：

- ✅ repo -完全控制私有存储库 - ✅ read:org -阅读组织和团队成员

1. 点击 “生成令牌”
2. 立即复制令牌（您将不会再看到它！）
3. 将其粘贴到您的 .env 文件

用法

本地运行

选项1：直接使用Python（stdio模式）

python github_crawler_server.py

这将在stdio模式下启动服务器，这对于使用MCP兼容客户端进行测试非常有用。

选项2：使用FastMCP CLI（stdio模式）

fastmcp run github_crawler_server.py:mcp

选项3:用于测试的HTTP服务器

fastmcp run github_crawler_server.py:mcp --transport http --port 8000

服务器将在以下时间可用 http://localhost:8000/mcp

测试服务器

运行测试脚本以验证所有工具是否正常工作：

python test_server.py

这将使用真实的GitHub API调用来测试每个工具。

可用工具

1. search_repositories

按查询搜索存储库。

# Example: Search for FastMCP repositories
search_repositories(query="fastmcp language:python", sort="stars", order="desc", per_page=10)

2. get_repository_details

获取特定存储库的全面详细信息。

# Example: Get details for jlowin/fastmcp
get_repository_details(owner="jlowin", repo="fastmcp")

3. list_user_repositories

列出用户或组织的所有存储库。

# Example: List all repos for a user
list_user_repositories(username="octocat", type="all", sort="updated")

4. get_repository_contents

浏览存储库中的文件和目录。

# Example: List root directory contents
get_repository_contents(owner="jlowin", repo="fastmcp", path="")

# Example: Get a specific file
get_repository_contents(owner="jlowin", repo="fastmcp", path="README.md")

5. get_repository_structure

获取存储库的完整目录树。

# Example: Get full structure
get_repository_structure(owner="jlowin", repo="fastmcp", branch="main")

6. get_repository_readme

获取markdown格式的README内容。

# Example: Read README
get_repository_readme(owner="jlowin", repo="fastmcp")

7. list_repository_commits

列出最近提交的详细信息。

# Example: Get last 20 commits
list_repository_commits(owner="jlowin", repo="fastmcp", per_page=20)

8. get_repository_languages

分析所使用的编程语言。

# Example: Get language breakdown
get_repository_languages(owner="jlowin", repo="fastmcp")

9. list_repository_issues

浏览存储库问题。

# Example: List open issues
list_repository_issues(owner="jlowin", repo="fastmcp", state="open", per_page=10)

10. get_file_content

下载并解码特定文件。

# Example: Get file content
get_file_content(owner="jlowin", repo="fastmcp", path="src/main.py")

部署到FastMCP云

1.推送到GitHub

git init
git add .
git commit -m "Initial commit: GitHub Crawler MCP Server"
git remote add origin https://github.com/yourusername/github-crawler-mcp.git
git push -u origin main

2.部署在FastMCP云上

1. 首选 FastMCP云
2. 使用您的GitHub帐户登录
3. 点击 “创建新项目”
4. 选择您的 github-crawler-mcp 仓库
5. 设置服务器入口点： github_crawler_server.py:mcp
6. 添加环境变量： GITHUB_TOKEN 使用您的代币价值
7. 点击 “部署”

您的服务器将被部署，您将获得一个URL，如下所示：

https://your-project.fastmcp.app/mcp

3.连接到ChatGPT

1. 打开ChatGPT
2. 前往设置→ 自定义指令或MCP设置
3. 添加您的FastMCP云服务器URL
4. 保存并开始在ChatGPT中使用GitHub爬虫工具！

ChatGPT查询示例

连接后，您可以向ChatGPT提出以下问题：

• *“在GitHub上搜索流行的Python web框架”*
• *“显示FastMCP存储库的README”*
• *“langchain存储库中使用了哪些编程语言？”*
• *“列出openai/openai python存储库中最近的提交”*
• *“给我反应存储库的结构”*
• *“显示tensorflow/tensorflow存储库中的未解决问题”*

速率限制

建议： 始终使用GitHub令牌用于生产，以确保您有足够的速率限制。

安全说明

⚠️ 重要提示：

• 永远不要承诺你的 .env 文件到版本控制（它位于 .gitignore)
• 部署到FastMCP Cloud时，添加 GITHUB_TOKEN 作为安全环境变量
• 使用具有最小安全范围的令牌
• 定期旋转令牌

故障排除

错误：“GitHub API错误：401”

• 您的GitHub令牌无效或已过期
• 生成新令牌并更新您的 .env 文件

错误：“GitHub API错误：403-超过速率限制”

• 您已超过费率限制
• 等待限制重置（检查 X-RateLimit-Reset 头球
• 如果在没有身份验证的情况下使用，请添加GitHub令牌

错误：“GitHub API错误：404”

• 存储库不存在或是私有的（您没有访问权限）
• 检查所有者和回购名称
• 如果需要，确保您的令牌可以访问私有存储库

工具返回空结果

• 检查您的搜索查询语法
• 验证存储库/用户是否存在
• 有些查询可能真的不返回结果

项目结构

github-crawler-mcp/
├── github_crawler_server.py  # Main MCP server
├── requirements.txt           # Python dependencies
├── .env.example              # Environment template
├── .env                      # Your config (not in git)
├── .gitignore               # Git ignore rules
├── test_server.py           # Test script
└── README.md               # This file

贡献

欢迎投稿！请随意：

• 报告错误
• 建议新功能
• 提交拉取请求
• 改进文档

许可证

MIT许可证-您可以在自己的项目中自由使用！

资源

• FastMCP文档
• MCP协议规范
• FastMCP云

______________________________________________________________________

内置于❤️ 使用FastMCP