GitHub v3 REST API MCP 服务器
这个MCP（模型内容协议）服务器通过STDIO传输模式与FastMCP一起，提供对GitHub v3 REST API功能的访问。
特点/特性
- 基于FastMCP且采用装饰器模式的服务器
- 通过@mcp.tool()装饰器实现工具的自动注册
- 类型安全的参数处理
- 全面的错误处理和日志记录
- 通过环境变量轻松配置
先决条件
- Python 3.10或更高版本
- pip包管理器
安装
- 安装依赖项：
pip install -r requirements.txt- 配置环境变量：
export API_BASE_URL="https://your-api-base-url"
export BEARER_TOKEN="your-bearer-token"
# Alternative authentication options (use only one):
# export API_KEY="your-api-key"
# export BASIC_AUTH="your-basic-auth-credentials"运行MCP服务器
STDIO 模式（默认）
服务器默认以STDIO模式运行，这非常适合与Cursor等AI助手直接集成：
python main.pyCursor/Claude 桌面版配置
将此添加到您的MCP配置文件中（例如。， ~/Library/Application Support/Cursor/User/globalStorage/@anthropic/mcp-server-registry/mcp.json)：
{
"mcpServers": {
"github-v3-rest-api-mcp-server": {
"command": "python",
"args": ["/path/to/your/project/main.py"],
"env": {
"API_BASE_URL": "https://your-api-base-url",
"BEARER_TOKEN": "your-bearer-token"
}
}
}
}环境变量
必需的
API_BASE_URLAPI端点的基础URL
认证（使用以下其中一种方法）
BEARER_TOKEN用于OAuth2/承载令牌认证的承载令牌API_KEYAPI密钥用于API密钥认证BASIC_AUTH基本认证凭据（base64编码）
注除非API明确不需要认证，否则应提供至少一个认证变量。
发展
对于支持自动重载的开发：
# Install development dependencies
pip install -r requirements.txt
# Run with Python
python main.py项目结构
.
├── main.py # Entry point with FastMCP server
├── config.py # Configuration management
├── models.py # Pydantic data models
├── tools/ # Auto-generated tools organized by category
│ ├── __init__.py
│ └── [category]/ # Tools grouped by API endpoint category
│ ├── __init__.py
│ └── *.py # Individual tool implementations
├── requirements.txt # Python dependencies
└── README.md # This file它是如何工作的
这个MCP服务器是使用FastMCP构建的，采用了基于装饰器的架构：
- FastMCP 服务器在（某处）创建一个MCP服务器实例
main.py - 工具装饰器每件工具都装饰着
@mcp.tool()用于自动注册 - 自动导入当导入工具模块时，工具会自动注册
- 类型安全使用Python类型提示进行参数验证
- 错误处理使用JSON错误响应进行全面的错误处理
示例工具
from main import mcp
@mcp.tool()
def get_users(search: str = None, page: int = None) -> str:
"""
Get users from the API.
Args:
search: Search query for filtering users
page: Page number for pagination
Returns:
JSON string with user data
"""
# Tool implementation...
return json.dumps(result, indent=2)认证方法
服务器支持多种认证方法：
Bearer Token（OAuth2）
export BEARER_TOKEN="your-bearer-token"API密钥
export API_KEY="your-api-key"基本认证
export BASIC_AUTH="base64-encoded-credentials"记录（日志）
服务器包含对标准错误输出（stderr）的全面日志记录：
- INFO级别：一般操作，工具注册
- 警告级别：跳过操作，缺少参数
- ERROR级别：API错误，请求失败
在您的MCP客户端控制台或标准错误输出中查看日志。
故障排除
“缺少必需参数”错误
- 检查是否提供了所有必需的参数
- 验证参数名称是否与工具定义相匹配
认证错误
- 确保设置了正确的认证环境变量
- 验证您的凭证是否有效且未过期
- 检查API_BASE_URL是否正确
导入错误
- 跑步
pip install -r requirements.txt确保所有依赖项都已安装 - 确认你使用的是 Python 3.10 或更高版本
未找到工具
- 验证工具名称是否与您的MCP客户端中显示的名称一致
- 检查工具目录结构
- 确保所有
__init__.py文件存在
生成的工具
此服务器是根据OpenAPI规范自动生成的。每个API端点都作为MCP工具暴露出来，并具有：
- 自动参数提取与验证
- 类型安全的参数处理
- 全面的错误处理
- JSON 响应格式化
使用您的MCP客户端的工具列表功能来查看所有可用工具。
贡献
这是一个生成的MCP服务器。要修改工具行为：
- 编辑工具的实现部分
tools/[category]/[tool_name].py - 保持
@mcp.tool()用于注册的装饰器 - 保留用于参数验证的函数签名
- 通过在本地运行服务器来测试更改
许可证
这个生成的MCP服务器遵循与生成工具相同的许可协议。