# github-stars-mcp

Your GitHub starred repos ("favorites") in a local SQLite cache, served over
[Model Context Protocol](https://modelcontextprotocol.io) — so you can search
and list your stars from Claude Desktop, Kimi Code, Cursor, VS Code, or any
other MCP client, with your own GitHub account.

```
GitHub API (GET /user/starred, paginated)
        │  ETag check on every use; full sync when changed
        ▼
SQLite  ~/.github-stars-mcp/stars.db  ──►  MCP server (stdio)  ──►  your MCP client
```

**Features**

- Zero-config freshness: every query checks GitHub with a conditional request
  (ETag). A `304 Not Modified` costs no rate-limit quota; a `200` triggers a
  full sync before answering.
- Instant, offline-friendly reads from a local SQLite cache.
- No native dependencies — uses Node's built-in `node:sqlite`.
- Your token never leaves your machine: plain env var, local `.env`, or your
  logged-in `gh` CLI.

## Requirements

- **Node.js ≥ 22.5** (for the built-in SQLite module)
- A way to authenticate with GitHub (any one of):
  1. `GITHUB_TOKEN` env var — a [personal access token](https://github.com/settings/tokens)
     (fine-grained tokens need no special scopes for public stars; classic tokens need `read:user`)
  2. `~/.github-stars-mcp/.env` with `GITHUB_TOKEN=...`
  3. the [GitHub CLI](https://cli.github.com/) logged in (`gh auth login`) — used automatically as a fallback

## Quick start (npx — straight from GitHub)

No npm account or registry needed; npx installs and builds straight from this
repo (the first run takes ~30s because it compiles TypeScript; after that it
runs from cache).

Prime the local cache (first sync):

```sh
npx -y github:ENFernandes/github-stars-mcp sync
```

Then add the server to your MCP client (see configs below):

```json
{
  "mcpServers": {
    "github-stars": {
      "command": "npx",
      "args": ["-y", "github:ENFernandes/github-stars-mcp"]
    }
  }
}
```

If you authenticate via option 1, pass the token through the client config:

```json
{
  "mcpServers": {
    "github-stars": {
      "command": "npx",
      "args": ["-y", "github:ENFernandes/github-stars-mcp"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    }
  }
}
```

To pin a specific release instead of tracking the default branch, append a tag:
`github:ENFernandes/github-stars-mcp#v0.1.0`.

### Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or
`%APPDATA%\Claude\claude_desktop_config.json` (Windows) — use the JSON block above.

### Kimi Code

`~/.kimi-code/mcp.json` (user level) or `.kimi-code/mcp.json` (project level) —
same block as above. Then `/mcp` in the TUI to verify.

### Cursor

Settings → MCP → add server, or edit `~/.cursor/mcp.json` — same block as above.

### VS Code

`.vscode/mcp.json` in your workspace (or user settings) uses a `servers` key:

```json
{
  "servers": {
    "github-stars": {
      "command": "npx",
      "args": ["-y", "github-stars-mcp"]
    }
  }
}
```

### Other clients

Any client that supports MCP stdio servers works: point it at
`npx -y github:ENFernandes/github-stars-mcp` (the `serve` subcommand is the default).

## Install from source

```sh
git clone https://github.com/ENFernandes/github-stars-mcp.git
cd github-stars-mcp
npm install
npm run sync    # builds and primes the cache
```

Then register the absolute path instead of npx:

```json
{
  "mcpServers": {
    "github-stars": {
      "command": "node",
      "args": ["/absolute/path/to/github-stars-mcp/dist/server.js"]
    }
  }
}
```

## MCP tools

| Tool | Description |
| --- | --- |
| `search_stars` | Keyword search over name, description, and topics; optional language filter |
| `list_stars` | List stars with language filter, sort (recent / stars / name), pagination |
| `get_star` | Full details for one repo by `owner/name` |
| `refresh_stars` | Force a full re-fetch from the GitHub API (rarely needed — see below) |
| `stars_status` | Show cache size and last check / last sync timestamps |

## How freshness works

Every use of a read tool (`search_stars`, `list_stars`, `get_star`) first asks
GitHub "did my starred list change?" with a **conditional request**
(`If-None-Match` + the ETag stored from the last sync):

- **304 Not Modified** → the query is answered from the local DB. The check
  costs one lightweight request that does **not** count against the rate limit.
- **200 OK** → something changed; the server runs a full sync before answering.
  The check's response is page 1 of the sync, so no request is wasted.

Checks are throttled to at most one per minute, and a failed check (offline,
token issue) never blocks reads — you just get the cached data.

Note: the conditional check watches page 1 (100 most recent stars). Adding a
star is always detected; an *unstar* beyond the 100 most recent may only be
picked up by a later change or an explicit `refresh_stars` /
`npx -y github:ENFernandes/github-stars-mcp sync`.

## Data and configuration locations

| What | Where | Override |
| --- | --- | --- |
| SQLite cache | `~/.github-stars-mcp/stars.db` | `GITHUB_STARS_DB` env var |
| Optional `.env` | `~/.github-stars-mcp/.env` | `GITHUB_STARS_HOME` env var |

## Development

```sh
npm run build    # type-check + compile to dist/
npm run smoke    # end-to-end stdio test: lists tools, runs real queries
```

Search uses SQL `LIKE`, which is plenty fast for thousands of stars; FTS5 can
be added later if needed. `node:sqlite` is marked experimental by Node — it
prints a harmless warning on stderr and does not affect the MCP protocol.

## License

[MIT](LICENSE)