README.md•3.33 kB
# GitHub MCP Server
A Model Context Protocol (MCP) server that connects to GitHub and provides tools for searching and retrieving public repository information.
## Features
- **Search Repositories**: Search for repositories using GitHub's search API
- **User Repositories**: Get repositories for a specific GitHub user
- **Repository Details**: Get detailed information about a specific repository
- **Trending Repositories**: Find trending repositories (approximated using search)
## Requirements
- Python 3.12+
- GitHub API access (optional token for higher rate limits)
## Installation
1. Clone or download this repository
2. Install dependencies:
```bash
pip install -r requirements.txt
```
3. (Optional) Set up GitHub token:
- Copy `env.example` to `.env`
- Add your GitHub token to `.env` for higher rate limits
- Get a token from: https://github.com/settings/tokens
## Usage
### Running the Server
```bash
python server.py
```
### Cursor Configuration
Add to your `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"github-mcp-server": {
"command": "python",
"args": ["/absolute/path/to/github-mcp-server/server.py"]
}
}
}
```
Restart Cursor after updating the configuration.
## Available Tools
### 1. Search Repositories
Search for public repositories on GitHub with various filters.
**Parameters:**
- `query`: Search query (e.g., "python machine learning", "language:javascript stars:>1000")
- `sort`: Sort by 'stars', 'forks', 'help-wanted-issues', 'updated'
- `order`: 'asc' or 'desc'
- `per_page`: Number of results (max 100)
### 2. Get User Repositories
Get repositories for a specific GitHub user.
**Parameters:**
- `username`: GitHub username
- `type`: 'public', 'private', or 'all' (public only works without token)
- `sort`: Sort by 'created', 'updated', 'pushed', 'full_name'
### 3. Get Repository Details
Get detailed information about a specific repository.
**Parameters:**
- `owner`: Repository owner username
- `repo`: Repository name
### 4. Get Trending Repositories
Get trending repositories (approximated using search with recent activity).
**Parameters:**
- `since`: 'daily', 'weekly', or 'monthly'
- `language`: Filter by programming language (optional)
## Example Usage in Cursor
Once configured, you can use these tools in Cursor chat:
- "Search for Python machine learning repositories with more than 1000 stars"
- "Show me all public repositories for the user 'torvalds'"
- "Get detailed information about the repository 'facebook/react'"
- "Find trending JavaScript repositories from this week"
## Rate Limits
- Without token: 60 requests/hour
- With token: 5000 requests/hour
## Error Handling
The server includes comprehensive error handling for:
- Invalid parameters
- GitHub API errors
- Network timeouts
- Rate limiting
## Development
### Running Tests
```bash
pytest
```
### Adding New Tools
To add new GitHub tools, follow this pattern in `server.py`:
```python
@app.tool()
def your_new_tool(param1: str, param2: int) -> Dict[str, Any]:
"""Description of what your tool does.
Args:
param1: Description of parameter 1
param2: Description of parameter 2
Returns:
Dictionary containing the results
"""
# Implementation here
pass
```
## License
MIT License