mcp_agent

GitHub Stars MCP Server

一个用于分析 GitHub 用户 Star 项目的 MCP (Model Context Protocol) 服务器。

功能特性

这个 MCP 服务器提供了以下工具来分析 GitHub 用户的 starred 项目：

1. get_starred_repos - 获取 Star 项目列表

获取指定 GitHub 用户的 starred 项目列表，包含详细信息。

参数：

• username (必需): GitHub 用户名
• limit (可选): 返回的最大项目数量

示例：

{
  "username": "torvalds",
  "limit": 10
}

2. analyze_starred_repos - 分析 Star 项目

对用户的 starred 项目进行全面分析，生成统计信息。

参数：

• username (必需): GitHub 用户名

分析包括：

• 总 star 数量统计
• 编程语言分布
• 主题（topics）分析
• 最多 star 的项目
• 最多 fork 的项目
• 最近 star 的项目
• 归档项目数量
• 平均 star 和 fork 数

示例：

{
  "username": "octocat"
}

3. search_starred_repos - 搜索 Star 项目

在用户的 starred 项目中搜索，支持在项目名称、描述和主题中搜索。

参数：

• username (必需): GitHub 用户名
• query (必需): 搜索关键词

示例：

{
  "username": "octocat",
  "query": "machine learning"
}

4. filter_starred_repos - 过滤 Star 项目

根据各种条件过滤 starred 项目。

参数：

• username (必需): GitHub 用户名
• language (可选): 按编程语言过滤
• topic (可选): 按主题过滤
• min_stars (可选): 最小 star 数量
• archived (可选): 按归档状态过滤 (true/false)

示例：

{
  "username": "octocat",
  "language": "Python",
  "min_stars": 1000,
  "archived": false
}

安装

依赖要求

• Python 3.10 或更高版本
• uv (推荐) 或 pip

使用 uv 安装（推荐）

# 克隆仓库
git clone <repository-url>
cd mcp_agent

# 使用 uv 安装依赖
uv pip install -e .

使用 pip 安装

# 克隆仓库
git clone <repository-url>
cd mcp_agent

# 安装依赖
pip install -e .

配置

GitHub Token（可选但推荐）

为了避免 GitHub API 速率限制，建议配置 GitHub Personal Access Token：

1. 在 GitHub 上创建 Personal Access Token：

   • 访问 https://github.com/settings/tokens
   • 点击 "Generate new token (classic)"
   • 选择权限：public_repo (用于访问公开仓库信息)
   • 生成并复制 token

2. 设置环境变量：

export GITHUB_TOKEN="your_token_here"

或者在使用 MCP 客户端时配置环境变量。

注意： 不使用 token 时，API 调用会受到速率限制（每小时 60 次请求）。使用 token 后限制提高到每小时 5000 次。

使用方法

作为 MCP 服务器运行

在 Claude Desktop 或其他 MCP 客户端中配置：

{
  "mcpServers": {
    "github-stars": {
      "command": "python",
      "args": ["-m", "github_stars_mcp"],
      "cwd": "/path/to/mcp_agent",
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

或者使用 uv：

{
  "mcpServers": {
    "github-stars": {
      "command": "uv",
      "args": ["run", "python", "-m", "github_stars_mcp"],
      "cwd": "/path/to/mcp_agent",
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

直接运行

# 设置 GitHub token（可选）
export GITHUB_TOKEN="your_token_here"

# 运行服务器
python -m github_stars_mcp

# 或使用 uv
uv run python -m github_stars_mcp

使用示例

示例 1：获取用户的 Star 项目

使用 get_starred_repos 工具获取 torvalds 的前 20 个 starred 项目

示例 2：分析 Star 项目统计

使用 analyze_starred_repos 工具分析 octocat 的 starred 项目

示例 3：搜索特定主题的项目

使用 search_starred_repos 工具在 octocat 的 starred 项目中搜索 "rust"

示例 4：过滤 Python 项目

使用 filter_starred_repos 工具过滤 octocat 的 starred 项目，
只显示 Python 语言且 star 数超过 1000 的项目

API 参考

GitHub API

本工具使用 GitHub REST API v3：

• 端点：GET https://api.github.com/users/{username}/starred
• 文档：https://docs.github.com/en/rest/activity/starring

速率限制

• 未认证请求：每小时 60 次
• 已认证请求：每小时 5000 次

开发

运行测试

# 安装开发依赖
uv pip install -e ".[dev]"

# 运行测试
pytest

项目结构

mcp_agent/
├── src/
│   └── github_stars_mcp/
│       ├── __init__.py
│       ├── __main__.py
│       ├── server.py          # MCP 服务器实现
│       └── github_client.py   # GitHub API 客户端
├── pyproject.toml
├── README.md
└── .gitignore

故障排除

常见问题

1. API 速率限制错误

   • 解决方案：配置 GitHub Personal Access Token

2. 用户名不存在

   • 检查用户名是否正确
   • 确保用户的 starred 项目是公开的

3. 网络连接错误

   • 检查网络连接
   • 确认可以访问 api.github.com

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

相关资源

• MCP 协议文档
• GitHub REST API 文档
• Claude Code 文档