github-stars-mcp

Your GitHub starred repos ("favorites") in a local SQLite cache, served over Model Context Protocol — 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 (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 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):

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

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

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

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

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

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:

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

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