**English** | **[한국어](README_ko.md)**

<p align="center">
  <h1 align="center">github-insight-mcp</h1>
  <p align="center">
    <strong>GitHub + npm + PyPI + deps.dev. One question, full picture.</strong>
  </p>
</p>

<p align="center">
  <a href="#"><img src="https://img.shields.io/badge/Python-3.10%2B-blue?logo=python&logoColor=white" alt="Python 3.10+"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green" alt="MIT License"></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Compatible-purple?logo=anthropic&logoColor=white" alt="MCP"></a>
  <a href="https://github.com/wjddusrb03/github-insight-mcp"><img src="https://img.shields.io/github/stars/wjddusrb03/github-insight-mcp?style=social" alt="GitHub Stars"></a>
</p>

---

An MCP server that combines **GitHub repository analysis + npm/PyPI package info + deps.dev security advisories** into a single research pipeline. **No API keys required.** One question gives you stars, forks, activity, downloads, dependencies, and security status.

## Why This Exists

Before adopting a library or contributing to a project, developers check:

1. GitHub for stars, activity, and maintenance status
2. npm/PyPI for version, downloads, and dependencies
3. deps.dev or Snyk for security vulnerabilities
4. Repeat for each alternative library

4 sites, 12 tabs, endless context switching. **github-insight-mcp** does all of this in a single tool call.

## Demo: `analyze_repo` Output

> **You:** "Analyze the expressjs/express repository"

> **Claude** calls `analyze_repo(owner="expressjs", repo="express")`:

```
# Repository Analysis: expressjs/express

## Overview

  Name: expressjs/express
  Description: Fast, unopinionated, minimalist web framework for node.
  Language: JavaScript
  License: MIT License
  Link: https://github.com/expressjs/express

## Stats

  Stars: 65,432
  Forks: 16,123
  Open Issues: 234
  Created: 2009-06-26
  Last Push: 2026-03-20

## Recent Activity (30 days)

  Commits: 12
  Issues: 45 (opened: 28, closed: 17)
  Pull Requests: 8 (merged: 5, open: 3)

## Top Contributors

  1. dougwilson (1,234 commits)
  2. tj (567 commits)
  ...

## Recent Releases

  - 4.21.2 (2026-03-15)
  - 4.21.1 (2026-02-28)
  - 4.21.0 (2026-01-10)
```

## Key Features

- **No API keys required** -- Install and use immediately. Optional GitHub token for higher rate limits
- **GitHub repository analysis** -- Stars, forks, activity, contributors, releases at a glance
- **Repository comparison** -- Side-by-side metrics for two repos
- **npm/PyPI package info** -- Version, downloads, dependencies, keywords
- **Security advisories** -- Vulnerability check via Google's deps.dev (Open Source Insights)
- **Repository search** -- Find repos by keywords, sorted by stars/forks/updated

## Tools

| Tool | Description |
|------|-------------|
| `analyze_repo` | **Main tool.** Comprehensive GitHub repository analysis |
| `compare_repos` | Side-by-side comparison of two repositories |
| `repo_activity` | Recent commits, issues, and PRs timeline |
| `check_package` | npm or PyPI package info with download stats |
| `check_security` | Security advisories + dependencies via deps.dev |
| `search_repos` | Search GitHub repositories |
| `api_status` | Check API availability and rate limits |

## Installation

### Automatic Setup (Recommended)

```bash
git clone https://github.com/wjddusrb03/github-insight-mcp.git
cd github-insight-mcp
pip install -r requirements.txt
python setup_wizard.py
```

No API key setup required. Restart Claude Desktop after installation and you're ready to go.

**Optional:** Set a GitHub Personal Access Token for higher rate limits (60 -> 5,000 requests/hour). The setup wizard will guide you through this.

### Manual Setup

**1. Install dependencies**

```bash
git clone https://github.com/wjddusrb03/github-insight-mcp.git
cd github-insight-mcp
pip install -r requirements.txt
```

**2. Add to Claude Desktop config**

Open your Claude Desktop config file:

- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux:** `~/.config/claude/claude_desktop_config.json`

Add the following to `mcpServers`:

```json
{
  "mcpServers": {
    "github-insight": {
      "command": "python",
      "args": ["/full/path/to/github-insight-mcp/server.py"]
    }
  }
}
```

**Optional:** To use a GitHub token, add an `env` field:

```json
{
  "mcpServers": {
    "github-insight": {
      "command": "python",
      "args": ["/full/path/to/github-insight-mcp/server.py"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}
```

Restart Claude Desktop.

## API Overview

| API | Key Required | Features |
|-----|-------------|----------|
| GitHub REST API | Optional (free token) | Repository metadata, commits, issues, PRs, contributors, releases, search |
| npm Registry | No | Package info, download stats |
| PyPI + pypistats.org | No | Package metadata, download stats |
| deps.dev (Google) | No | Dependency analysis, security advisories, license info |

All APIs are free. GitHub works without a token (60 req/hr) but a free token gives 5,000 req/hr.

## Tool Reference

### `analyze_repo`

The main tool. Fetches repository overview, stats, recent activity, contributors, and releases.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `owner` | string | *(required)* | Repository owner (e.g. 'facebook') |
| `repo` | string | *(required)* | Repository name (e.g. 'react') |

### `compare_repos`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `owner1` | string | *(required)* | First repo owner |
| `repo1` | string | *(required)* | First repo name |
| `owner2` | string | *(required)* | Second repo owner |
| `repo2` | string | *(required)* | Second repo name |

### `repo_activity`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `owner` | string | *(required)* | Repository owner |
| `repo` | string | *(required)* | Repository name |
| `days` | int | `30` | Days to look back |

### `check_package`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `name` | string | *(required)* | Package name (e.g. 'express', 'requests') |
| `ecosystem` | string | `"npm"` | `"npm"` or `"pypi"` |

### `check_security`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `name` | string | *(required)* | Package name |
| `version` | string | *(required)* | Exact version (e.g. '4.17.20') |
| `ecosystem` | string | `"npm"` | `"npm"` or `"pypi"` |

### `search_repos`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | string | *(required)* | Search keywords |
| `sort` | string | `"stars"` | `"stars"`, `"forks"`, or `"updated"` |
| `count` | int | `10` | Number of results |

## Usage Examples

After installation, just talk to Claude naturally:

**Repository analysis:**
> "Analyze the facebook/react repository"

**Compare libraries:**
> "Compare expressjs/express vs fastify/fastify"

**Check activity:**
> "Show me recent activity for pallets/flask"

**Package info:**
> "Check the express package on npm"
> "What's the latest version of requests on PyPI?"

**Security check:**
> "Are there any security issues in lodash 4.17.20?"

**Search repos:**
> "Find popular MCP server repositories"

## Requirements

- Python 3.10+
- [Claude Desktop](https://claude.ai/download) (MCP support)
- API keys: **None required** (optional GitHub token for higher rate limits)

### Dependencies

| Package | Version | Purpose |
|---------|---------|---------|
| `mcp` | >= 1.0.0 | MCP SDK (FastMCP server framework) |
| `httpx` | >= 0.27.0 | HTTP client for API calls |
| `python-dotenv` | >= 1.0.0 | .env file loading (for optional GitHub token) |

## Project Structure

```
github-insight-mcp/
    server.py           # MCP server with 7 tools
    setup_wizard.py     # Interactive setup script
    core/
        github.py       # GitHub REST API client
        npm.py          # npm Registry API client
        pypi.py         # PyPI + pypistats client
        deps.py         # deps.dev (Google) API client
    requirements.txt    # Python dependencies
    pyproject.toml      # Package metadata
    LICENSE             # MIT License
```

## Issues & Feedback

Found a bug or have an idea? Please open an issue:

- [GitHub Issues](https://github.com/wjddusrb03/github-insight-mcp/issues)

When reporting a bug, please include:
- Operating system (Windows / macOS / Linux)
- Python version (`python --version`)
- Error message or unexpected behavior
- Steps to reproduce

Pull requests are welcome!

## License

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

---

Stop opening 12 tabs to evaluate a library. Just ask Claude.