# GitHub Trending MCP Server

A Model Context Protocol (MCP) server that fetches GitHub trending repositories and filters them by keywords, programming language, and time period.

### Key Features

- Fetch trending repositories from GitHub
- Filter by keywords (default: "mcp", "model context protocol", "skill")
- Filter by programming language (Python, TypeScript, Rust, etc.)
- Filter by time period (daily, weekly, monthly)
- Rich response format with keyword match details and locations
- Runs as a standard MCP server over stdio

## Installation

### From PyPI

```bash
pip install yw-github-trending-mcp
```

### From Source

```bash
git clone https://github.com/snyangwei2/yw-github-trending-mcp.git
cd yw-github-trending-mcp
pip install -e .
```

## Configuration

Add the server to your MCP client configuration. Below are examples for Claude Desktop.

### Claude Desktop (macOS)

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "github-trending": {
      "command": "python",
      "args": ["-m", "github_trending_mcp"]
    }
  }
}
```

### Claude Desktop (Windows)

Edit `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "github-trending": {
      "command": "cmd",
      "args": ["/c", "python", "-m", "github_trending_mcp"]
    }
  }
}
```

> **Tip:** If you installed the package in a virtual environment, use the full path to the Python binary instead of just `"python"`.

## Usage

Once configured, you can ask your MCP client natural language questions like:

- "Show me trending MCP repositories on GitHub"
- "What are the trending Python repositories this week?"
- "Find trending repos related to model context protocol"
- "Show me weekly trending Rust projects"
- "Are there any trending repositories about skills or MCP?"

The server will scrape GitHub Trending, filter results by your criteria, and return a formatted markdown response.

## Tool: `get_trending_repos`

The server exposes a single tool with the following parameters:

| Parameter | Type | Required | Description |
|---|---|---|---|
| `keywords` | `string[]` | No | Keywords to match in repo names and descriptions. Default: `["mcp", "model context protocol", "skill"]` |
| `language` | `string` | No | Programming language filter (e.g., `"python"`, `"typescript"`, `"rust"`) |
| `since` | `string` | No | Time period: `"daily"` (default), `"weekly"`, or `"monthly"` |
| `spoken_language` | `string` | No | Human language filter (e.g., `"en"`, `"zh"`, `"ja"`) |

### Example Response

```markdown
# GitHub Trending Repositories

Found 3 repositories matching keywords: mcp, model context protocol, skill

## 1. anthropics/mcp-server
**URL:** https://github.com/anthropics/mcp-server
**Description:** Reference implementation of the Model Context Protocol
**Language:** TypeScript
**Stars:** 12,345 (+230 today)
**Forks:** 1,024
**Matched Keywords:** mcp, model context protocol
  - 'mcp' found in: name, description
  - 'model context protocol' found in: description
```

## Development

### Setup

```bash
git clone https://github.com/snyangwei2/yw-github-trending-mcp.git
cd yw-github-trending-mcp
pip install -e ".[dev]"
```

### Run Tests

```bash
pytest
```

### Format Code

```bash
black src/ tests/
```

### Type Check

```bash
mypy src/
```

### Lint

```bash
ruff check src/ tests/
```

## Publishing

### PyPI

```bash
pip install build twine
python -m build
twine upload dist/*
```

## License

MIT License. See [LICENSE](LICENSE) for details.

## Contributing

Contributions are welcome! To get started:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/my-feature`)
3. Make your changes and add tests
4. Run the test suite (`pytest`)
5. Run formatting and linting (`black src/ tests/ && ruff check src/ tests/`)
6. Submit a pull request