# OSSInsight MCP Server

A Model Context Protocol (MCP) server for querying GitHub repository analytics from [OSSInsight](https://ossinsight.io) (by PingCAP). Provides repo metadata, trending repos, curated collections, search, compare, and collection rankings — no API key required.

## Features

- **`ossinsight_repo`** — GitHub repo metadata: stars, forks, language, license, description
- **`ossinsight_trending`** — Trending repos by language and timeframe
- **`ossinsight_collections`** — List all 102 curated collections
- **`ossinsight_search`** — Search repos and collections by keyword
- **`ossinsight_compare`** — Side-by-side comparison of two repos
- **`ossinsight_ranking`** — Rank repos in a collection by stars, issues, or PRs

## Installation

### uv (recommended)

```bash
uvx ossinsight-mcp
```

### pip

```bash
pip install ossinsight-mcp
ossinsight-mcp
```

## Configuration

### Claude Desktop

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

### Cursor / VS Code

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

## Tools

| Tool | Description | Key Params |
|------|-------------|-----------|
| `ossinsight_repo` | Repo metadata — stars, forks, language, license | `owner`, `repo` (required) |
| `ossinsight_trending` | Trending repos by language/timeframe | `language`, `period` (past_24h/past_week/past_month/past_3mo) |
| `ossinsight_collections` | List all curated collections | (none) |
| `ossinsight_search` | Search repos and collections | `q` (required), `page`, `page_size`, `sort` |
| `ossinsight_compare` | Compare two repos side-by-side | `repo1`, `repo2` (required) |
| `ossinsight_ranking` | Rank repos in a collection | `collection_id` (required), `metric`, `range` |

## Examples

```python
# Get repo metadata
ossinsight_repo({"owner": "grafana", "repo": "grafana"})
# → stars: 76K, forks: 14K, language: TypeScript, license: AGPL-3.0

# What's trending in Rust this month
ossinsight_trending({"language": "rust", "period": "past_month"})

# List all collections
ossinsight_collections({})

# Compare two databases
ossinsight_compare({"repo1": "postgres/postgres", "repo2": "clickhouse/clickhouse"})

# Top repos in the AI/ML collection by stars this year
ossinsight_ranking({"collection_id": 12, "metric": "stars", "range": "year"})
```

## Data Source

Uses the [OSSInsight API](https://ossinsight.io) (`/api/mcp`).

- **Auth:** None required
- **Rate limit:** 600 requests per hour per IP
- **Data:** GH Archive (all public GitHub events since 2011)

## Development

```bash
git clone https://github.com/GeniusTechnoMystic/ossinsight-mcp.git
cd ossinsight-mcp
uv sync
uv run ossinsight-mcp
```

## Related Projects

Other OSSInsight MCP servers in the ecosystem:

| Project | Language | Tools | Tests | Install | Differentiator |
|---------|----------|-------|-------|---------|---------------|
| **[damonxue/mcp-ossinsight](https://github.com/damonxue/mcp-ossinsight)** | Python | 5 | None | `npx` / Docker | Developer analysis, natural language query, web scraping fallback |
| **[gztchan/ossinsight-mcp](https://github.com/gztchan/ossinsight-mcp)** | Python | 4 | None | git clone | Stargazer/issue/PR creator demographics, generic request tool |
| **This one** (ours) | **Python** | **6** | **28 tests** | **`uvx` / `pip install`** | **Collections, search, compare, ranking, PyPI-published** |

### Our differentiators

- **Broadest open-source tool set** — 6 tools covering repo metadata, trending, collections, search, compare, and ranking. The only open-source server with dedicated tools for collections, search, and compare.
- **Test coverage** — 28 tests with mocked HTTP (respx). No competitor has tests.
- **PyPI publication** — install with `uvx ossinsight-mcp` or `pip install ossinsight-mcp`. No npm, no Docker, no build step.
- **Ranking flexibility** — `ossinsight_ranking` supports stars, issues, or PRs across day/week/month/year ranges.

### When to use the alternatives

- **damonxue/mcp-ossinsight** — if you need developer contribution analysis, natural language queries, or web scraping for repos with <25 stars.
- **gztchan/ossinsight-mcp** — if you need stargazer/issue/PR creator demographics (countries, history) or a generic forward-compatible request tool.

### Scope note

None of the open-source OSSInsight MCP servers fully wrap the [OSSInsight Public API v1beta](https://ossinsight.io/docs/api). A hosted 18-tool OSSInsight MCP server exists on mcpbundles.com covering issue creator, PR creator, and stargazer demographics (countries, history, orgs) — but it's not open source.

## License

MIT