github-rag-mcp

github-rag-mcp

Stdio MCP proxy that bridges local MCP clients (Claude Desktop, Claude Code, etc.) to a remote github-rag-mcp Cloudflare Worker for semantic and structured search over GitHub issues, pull requests, releases, documentation, GitHub Wiki pages, commit diffs, and comment / review surfaces (issue/PR top-level comments, PR review bodies, PR inline review comments).

This package is the client-side proxy only. The actual indexing pipeline (Vectorize + D1 FTS5 + Workers AI BGE-M3 + cross-encoder rerank) runs on the Worker. See the main repository for architecture and self-hosting instructions.

Breaking change: MCP protocol revision 2026-07-28

From this release the Worker serves MCP protocol revision 2026-07-28 only, with no compatibility lane for the previous revision.

• Proxy versions older than this release stop working. They open a session with initialize, which the Worker no longer answers. The failure is quiet: the proxy does not crash, it returns the protocol error as tool output text.
• Restart Claude Desktop to pick up the new proxy. npx resolves @latest at process start, so an already-running Claude Desktop keeps the copy it launched with however new the published version is. Quit it fully and reopen.
• Pinning the proxy version leaves you stuck. If your MCP client config pins a version older than this release, restarting does not help; remove the pin (or move it forward) first.

Nothing else changes for you: the proxy still speaks the same MCP dialect to Claude Desktop, and the same search tool with the same parameters.

What this proxy does

• Speaks stdio MCP locally to your client (SDK v1, unchanged by the revision above).
• Forwards tools/call to the Worker's /mcp endpoint over MCP protocol revision 2026-07-28. That side is stateless: no initialize handshake and no session id — each call carries the revision's per-request envelope.
• Handles OAuth 2.1 with PKCE against the Worker (browser-based localhost callback).
• Caches access and refresh tokens under ~/.github-rag-mcp/ (mode 0600).

Requirements

• Node.js >= 18
• A reachable github-rag-mcp Worker (the public default is https://github-rag-mcp.liplus.workers.dev; you can also point at your own deployment)
• A web browser on the same machine (used once for OAuth authorization)

Install / Run

The proxy is published to npm and exposes a github-rag-mcp binary.

Run directly with npx (no global install required):

npx github-rag-mcp

Or install globally:

npm install -g github-rag-mcp
github-rag-mcp

The first run opens a browser window to complete OAuth against the Worker. After authorization, tokens are stored under ~/.github-rag-mcp/ and refreshed automatically.

Client configuration

Claude Desktop / Claude Code

Add the server to your MCP client configuration. Example for Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "github-rag": {
      "command": "npx",
      "args": ["-y", "github-rag-mcp"],
      "alwaysLoad": true
    }
  }
}

To target a self-hosted Worker, set the RAG_WORKER_URL environment variable:

{
  "mcpServers": {
    "github-rag": {
      "command": "npx",
      "args": ["-y", "github-rag-mcp"],
      "env": {
        "RAG_WORKER_URL": "https://your-worker.example.workers.dev"
      },
      "alwaysLoad": true
    }
  }
}

Note on alwaysLoad: Recognized by Claude Code v2.1.121+ (released 2026-04-28). When set, the client loads this server's tools at session start instead of deferring them behind a ToolSearch round-trip — useful for retrieval servers used on every turn. Older clients (such as Claude Desktop) silently ignore the field, so it is safe to leave in place.

Configuration

Variable	Required	Default	Description
RAG_WORKER_URL	No	https://github-rag-mcp.liplus.workers.dev	Base URL of the Cloudflare Worker that exposes the MCP endpoint and OAuth metadata.

OAuth client registration and tokens are stored in:

• ~/.github-rag-mcp/oauth-client.json (dynamic client registration)
• ~/.github-rag-mcp/oauth-tokens.json (access + refresh tokens)

The proxy reuses a cached client registration only when it includes every redirect URI required by the current localhost callback listener. Because the listener uses a random port, a registration from a previous authorization may be replaced automatically before the browser opens.

Delete these files to force a fresh authorization flow.

Tools exposed

A single consolidated tool, search, covers every retrieval mode. Earlier builds split these across get_issue_context, get_doc_content, and list_recent_activity; those tools have been removed and their use cases now fold into the parameters of search.

Tool

Description

search

Unified search across GitHub issues, pull requests, releases, repository documentation, GitHub Wiki pages, commit diffs, and comment / review surfaces. Three modes are selected by the combination of query and sort: (1) hybrid semantic search — dense BGE-M3 over Vectorize + sparse BM25 over D1 FTS5, fused via RRF, then re-scored with the bge-reranker-base cross-encoder; (2) time-ordered activity scan — leave query empty and set sort to updated_desc / created_desc, optionally narrowed with since / until; (3) doc / wiki content fetch — set include_content: true to inline raw markup on top doc and wiki_doc rows. Structured filters (repo, state, labels, milestone, assignee, type, top_k, fusion, rerank) apply in every mode. Search mode also accepts an opt-in graph_expand (with graph_hops, 1 or 2) that performs a GraphRAG expansion over the Decision-Structure mention graph and appends related wiki entries; it is off by default.

The type filter accepts: issue, pull_request, release, doc, wiki_doc, diff, issue_comment, pr_review, pr_review_comment, or all (default).

search is read-only. For the full parameter reference and examples, see the main repository README.

Authentication flow

• On first tool call, the proxy discovers OAuth metadata at ${RAG_WORKER_URL}/.well-known/oauth-authorization-server.
• It performs Dynamic Client Registration (RFC 7591) if no compatible client is cached for the current localhost callback URIs.
• It starts a one-shot localhost HTTP listener on a random port and opens the browser to the Worker's authorization endpoint.
• After you approve, the Worker redirects to http://127.0.0.1:<port>/callback with an authorization code.
• The proxy exchanges the code for tokens (PKCE S256) and saves them.
• Subsequent calls reuse the access token and silently refresh when it nears expiry. On 401 from the Worker, the proxy invalidates its cached tokens and re-authenticates.

The browser callback never leaves your machine; the authorization code is delivered directly to the local listener.

Troubleshooting

• Browser does not open. The proxy logs the authorization URL to stderr; copy it into a browser manually.
• redirect_uri is not associated with this application. Upgrade the proxy. Current versions replace cached client registrations whose redirect URI set does not cover the callback port selected for this authorization.
• OAuth callback timed out after 5 minutes. Re-invoke any tool to restart the flow.
• Failed to reach worker. Check that RAG_WORKER_URL is correct and reachable from your machine.
• Unsupported protocol version, or a tool that answers with a protocol error instead of results. The proxy predates the 2026-07-28 flip. Quit Claude Desktop fully and reopen so npx fetches the current version; if your config pins a version, move the pin forward first.
• Stale credentials. Remove ~/.github-rag-mcp/oauth-tokens.json (and optionally oauth-client.json) and retry.

Links

• Source and architecture: https://github.com/Liplus-Project/github-rag-mcp
• Self-hosting the Worker: docs/installation.md
• Requirements spec: docs/0-requirements.md
• Issue tracker: https://github.com/Liplus-Project/github-rag-mcp/issues

License

Apache-2.0. See the LICENSE and NOTICE files in the main repository.