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.

What this proxy does

• Speaks stdio MCP locally to your client.
• Forwards tools/call to the Worker's Streamable HTTP MCP endpoint (/mcp).
• 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 silently ignore the field, so it is safe to leave in place. alwaysLoad を認識しないクライアント (Claude Desktop など) では無視されるだけで害はない。

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)

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. |

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

1. On first tool call, the proxy discovers OAuth metadata at ${RAG_WORKER_URL}/.well-known/oauth-authorization-server.
2. It performs Dynamic Client Registration (RFC 7591) if no client is cached.
3. It starts a one-shot localhost HTTP listener on a random port and opens the browser to the Worker's authorization endpoint.
4. After you approve, the Worker redirects to http://127.0.0.1:<port>/callback with an authorization code.
5. The proxy exchanges the code for tokens (PKCE S256) and saves them.
6. 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.
• 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.
• 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.