Metadata-Version: 2.4
Name: github-trending-mcp
Version: 0.2.1
Summary: A Model Context Protocol (MCP) server that provides GitHub trending repositories (supports both stdio and SSE transports)
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,sse,stdio,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
Requires-Dist: starlette>=0.27.0
Requires-Dist: uvicorn>=0.20.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.

**Supports both stdio and SSE transports!**

## 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
- 🔌 **Two transport modes:** stdio (for Claude Desktop/Cursor) and SSE (for web/remote access)

## 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
```

## Transport Modes

This package provides **two commands** for different use cases:

| Command | Transport | Use Case |
|---------|-----------|----------|
| `github-trending-mcp` | stdio | Claude Desktop, Cursor, local CLI |
| `github-trending-mcp-sse` | SSE (HTTP) | Web apps, remote access, multi-client |

---

## 📡 Mode 1: stdio (Default)

Best for local MCP clients like Claude Desktop and Cursor.

### Configuration for Claude Desktop / Cursor

Add 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`

#### Using uvx (✅ Recommended)

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

#### Using python -m (If uvx not available)

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

---

## 🌐 Mode 2: SSE (HTTP Server)

Best for web applications, remote access, or when multiple clients need to connect.

### Start the SSE Server

```bash
# Default: http://127.0.0.1:8000
github-trending-mcp-sse

# Custom host and port
github-trending-mcp-sse --host 0.0.0.0 --port 8080

# Using uvx
uvx github-trending-mcp-sse --port 8000
```

### SSE Server Options

| Option | Default | Description |
|--------|---------|-------------|
| `--host` | `127.0.0.1` | Host to bind to |
| `--port` | `8000` | Port to bind to |

### Configuration for SSE Mode

```json
{
  "mcpServers": {
    "github-trending": {
      "url": "http://localhost:8000/sse"
    }
  }
}
```

### Remote Access with ngrok

For temporary remote access without deploying to a cloud server:

```bash
# Terminal 1: Start SSE server
github-trending-mcp-sse --port 8000

# Terminal 2: Expose with ngrok
ngrok http 8000
```

Then use the ngrok URL in your configuration:

```json
{
  "mcpServers": {
    "github-trending": {
      "url": "https://xxxx-xx-xx-xxx-xx.ngrok.io/sse"
    }
  }
}
```

---

## Troubleshooting

### "Command not found" Error

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

1. **Recommended:** Use the uvx method
2. **Alternative:** Use `python3 -m` method
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)

