Metadata-Version: 2.4
Name: github-trending-mcp
Version: 0.1.1
Summary: A Model Context Protocol (MCP) server that provides GitHub trending repositories
Project-URL: Homepage, https://github.com/wwango/github-trending-mcp
Project-URL: Repository, https://github.com/wwango/github-trending-mcp
Project-URL: Issues, https://github.com/wwango/github-trending-mcp/issues
Author: wwango
License-Expression: MIT
License-File: LICENSE
Keywords: ai,github,llm,mcp,trending
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# GitHub Trending MCP Server

[![PyPI version](https://badge.fury.io/py/github-trending-mcp.svg)](https://badge.fury.io/py/github-trending-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

A Model Context Protocol (MCP) server that provides GitHub trending repositories information. This server allows LLMs to fetch and analyze trending repositories on GitHub.

## Features

- 🔥 Get real-time GitHub trending repositories
- 🌐 Filter by programming language (Python, JavaScript, Rust, Go, etc.)
- 📅 Filter by time range (daily, weekly, monthly)
- 🗣️ Filter by spoken language (Chinese, English, Japanese, etc.)
- 📊 Returns detailed repository information including stars, forks, description, and contributors

## Prerequisites

**Recommended:** Install [uv](https://docs.astral.sh/uv/) for the best experience:

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

## Installation

### Option 1: Using uvx (Recommended - No installation needed)

Just configure your MCP client directly, uvx will handle everything automatically.

### Option 2: Using pip

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

## Configuration

### Claude Desktop / Cursor Configuration

Add the following to your configuration file:

- **Claude Desktop (macOS)**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Claude Desktop (Windows)**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Cursor**: `~/.cursor/mcp.json`

#### Method 1: Using uvx (✅ Recommended)

```json
{
  "mcpServers": {
    "github-trending": {
      "command": "uvx",
      "args": ["github-trending-mcp"]
    }
  }
}
```

#### Method 2: Using python -m (If uvx not available)

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

> **Note:** Make sure `github-trending-mcp` is installed via `pip install github-trending-mcp` first.

#### Method 3: Using pipx

```bash
# Install pipx first if not available
pip install pipx
pipx install github-trending-mcp
```

```json
{
  "mcpServers": {
    "github-trending": {
      "command": "github-trending-mcp"
    }
  }
}
```

## Troubleshooting

### "Command not found" Error

If you see a red dot or "Error" status in your MCP client:

1. **Recommended:** Use the uvx method (Method 1 above)
2. **Alternative:** Use `python3 -m` method (Method 2 above)
3. **Check PATH:** If using pip install, ensure Python's bin directory is in your PATH

### Find your Python path

```bash
# macOS/Linux
which python3

# Windows
where python
```

Then use the full path in your configuration:

```json
{
  "mcpServers": {
    "github-trending": {
      "command": "/full/path/to/python3",
      "args": ["-m", "github_trending_mcp"]
    }
  }
}
```

## Available Tools

### `get_github_trending`

Fetches GitHub trending repositories with optional filters.

**Parameters:**

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `language` | string | Programming language filter (e.g., 'python', 'javascript', 'rust') | `""` (all) |
| `since` | string | Time range: 'daily', 'weekly', or 'monthly' | `"daily"` |
| `spoken_language` | string | Spoken language code (e.g., 'zh', 'en', 'ja') | `""` (all) |

**Example Usage:**

```
Get the trending Python repositories this week
```

```
Show me trending Rust projects with Chinese descriptions
```

```
What are the monthly trending JavaScript repositories?
```

## Response Format

The tool returns formatted markdown with repository information:

```markdown
# GitHub Trending Repositories

**Filters:** Language: python, Period: daily, Spoken Language: All

**Total:** 25 repositories

---

## 1. [owner/repo-name](https://github.com/owner/repo-name)

📝 Repository description here

- ⭐ Stars: 1,234
- 🍴 Forks: 567
- 💻 Language: Python
- 📈 234 stars today
- 👥 Built by: user1, user2, user3
```

## Development

### Clone the repository

```bash
git clone https://github.com/wwango/github-trending-mcp.git
cd github-trending-mcp
```

### Install dependencies

```bash
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"
```

### Run tests

```bash
pytest
```

### Build the package

```bash
python -m build
```

## License

MIT License - see [LICENSE](LICENSE) for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Acknowledgments

- Built with [MCP (Model Context Protocol)](https://modelcontextprotocol.io/)
- Data sourced from [GitHub Trending](https://github.com/trending)
