github-trending-mcp 0.2.1

A Model Context Protocol (MCP) server that provides GitHub trending repositories (supports both stdio and SSE transports)

GitHub Trending MCP Server

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 for the best experience:

# 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

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)

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

Using python -m (If uvx not available)

{
  "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

# 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

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

Remote Access with ngrok

For temporary remote access without deploying to a cloud server:

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

{
  "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

# macOS/Linux
which python3

# Windows
where python

Then use the full path in your configuration:

{
  "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:

# 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

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

Install dependencies

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

Run tests

pytest

Build the package

python -m build

License

MIT License - see LICENSE for details.

Contributing

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

Acknowledgments

• Built with MCP (Model Context Protocol)
• Data sourced from GitHub Trending