GitHub Text MCP Worker

中文说明 · Protocol and limits · Security

A self-hosted Cloudflare Worker that gives an MCP client explicit, verifiable access to GitHub text files. Read a file at a full commit SHA, continue through UTF-8-safe chunks, and compare the returned Git blob identity. When you enable write permissions, commit several file changes in one non-force branch update and inspect the readback receipts.

The deployment binds each endpoint to one repository. Tool arguments cannot redirect requests to a different owner or repository. Two independent endpoints are available; using only the primary endpoint is supported.

What it provides

• Immutable reads, directory/tree listings, literal file search, and commit metadata.

• Text responses with file identity, byte counts, continuation offsets, and deployment diagnostics. Empty files return an explicit envelope rather than a missing response.

• Optional single-commit writes and deletions, plus branch creation and guarded deletion.

• Separate connector credentials, GitHub tokens, and rate-limit bindings for the two repositories.

• Local tests using fixtures and mocked GitHub responses. The project does not provide a public demo service.

This is a focused text bridge for GitHub.com. It does not execute repository code, extract PDFs, retrieve Git LFS objects, provide an OAuth server, or replace a full Git client. The original integration target was Perplexity. A different host must support Streamable HTTP requests with a configurable Authorization: Bearer … header; compatibility with an untested Claude or other client is not promised. Hosts that require OAuth and cannot accept a manual Bearer header need an additional authorization layer, which is outside this project.

Related MCP server: github-mcp

Quick start

You need Node.js 24 or later, npm, Git, a Cloudflare account with Workers enabled, and access to the GitHub repository you want to expose.

1. Install and configure

git clone https://github.com/LyuPeng-star/github-text-mcp-worker.git
cd github-text-mcp-worker
npm ci
npx wrangler login

Edit wrangler.jsonc:

• Set name to an available Worker name for your Cloudflare account.

• Set vars.PRIMARY_REPOSITORY to your actual owner/repository.

• Leave vars.SECONDARY_REPOSITORY as "" if you need only one repository.

• Keep the endpoint rate-limit bindings and WORKER_VERSION_METADATA binding. If you deploy multiple Worker instances in the same account, give each endpoint's limiter a namespace_id that is unique within that account; reusing IDs can share counters across instances.

The shipped example-owner/example-repository value deliberately fails closed. A blank, malformed, or placeholder repository is unavailable; it never falls back to another repository. The default configuration uses workers.dev, disables preview URLs explicitly, and requires no custom domain.

2. Create credentials

Create a fine-grained GitHub personal access token for the correct resource owner and select only the target repository:

Set an expiration date and plan to replace the deployed token before it expires. Organization approval, repository rules, and protected branches can still limit access. Updating workflow files can require additional GitHub permissions; do not grant them unless that operation is intended. GitHub code-index search also depends on the upstream search API's support for your credential and repository. See GitHub's token guide and endpoint permission reference.

Create a separate, long random connector token in your password manager. This is the credential your MCP host sends to the Worker. It is not your GitHub token.

Store both values through Wrangler's interactive prompts:

npx wrangler secret put CONNECTOR_TOKEN_PRIMARY
npx wrangler secret put GITHUB_TOKEN_PRIMARY

Do not put real credentials in wrangler.jsonc, source files, client screenshots, or command-line arguments. Wrangler secrets are described in Cloudflare's documentation.

A read-only GitHub token is the way to restrict upstream mutations. The Worker advertises its write tools even with a read-only token; it does not implement separate per-tool roles or a write-enable switch.

3. Check and deploy

npm run check
npm test
npm run test:acceptance
npx wrangler deploy --dry-run

For a Git checkout, commit your nonsecret configuration before using the deployment guard:

git add wrangler.jsonc
git commit -m "Configure repository binding"
npm run deploy

npm run deploy requires a clean tracked and untracked working tree, obtains the actual 40-character HEAD, and injects SOURCE_COMMIT and a source tag. It supports local forks, other branch names, and detached HEAD; it does not require this repository's upstream remote.

If you downloaded a source archive without .git, use WRANGLER_SEND_METRICS=false npx wrangler deploy in a POSIX shell instead (or set the same environment variable in your shell). The service still works, but source_commit is unavailable unless you supply a genuine source identity. Do not invent one. The Wrangler configuration reference covers account-specific deployment settings.

4. Connect an MCP host

Use the URL printed by Wrangler, with this path:

https://<worker-name>.<account-subdomain>.workers.dev/primary/mcp

Configure a custom request header:

Authorization: Bearer <your-primary-connector-token>

Choose Streamable HTTP if your host asks for a transport. Requests use POST and Content-Type: application/json. This endpoint has no separate legacy /sse route, OAuth discovery flow, or persistent server-to-client stream. A host requiring those features is not compatible without an adapter.

If the host supplies an Origin header, the default allowed origins are https://perplexity.ai and https://www.perplexity.ai. For another origin, set the optional ALLOWED_ORIGINS variable to a comma-separated list of exact origins and redeploy. This replaces the defaults; it does not configure browser CORS or prove client compatibility. Server-to-server requests without Origin are accepted subject to authentication and other checks.

Start with resolve_ref, then call stat_file and get_file_text using its complete commit_sha. Keep that same SHA for all chunks of a file. See the protocol guide for continuation and verification details.

Optional second repository

Set SECONDARY_REPOSITORY to another actual owner/repository, then add:

npx wrangler secret put CONNECTOR_TOKEN_SECONDARY
npx wrangler secret put GITHUB_TOKEN_SECONDARY

Use a separate connector token and a separate fine-grained GitHub token scoped to that repository. Redeploy your updated, committed configuration. The second endpoint is /secondary/mcp; it uses MCP_RATE_LIMITER_SECONDARY. Its credentials and repository binding do not fall back to the primary endpoint. A primary-only deployment does not require either secondary secret.

Tools

All tools operate within the endpoint's configured repository. The schemas returned by tools/list are authoritative.

File reads require complete 40-hex commit SHAs; branch names, tags, short SHAs, and revision expressions are not interchangeable with them. resolve_ref and write operations default to the branch name main, not the repository's detected default; specify another name when needed.

Operational boundaries

• A file read is limited to 1,310,720 bytes. Text chunks default to 65,536 bytes; use continuation rather than assuming a large file was returned in full.

• A write call accepts 1–20 combined write/delete paths and at most 262,144 bytes of new UTF-8 content. It is a complete-file API, not a patch API.

• Atomic writes publish one commit by a non-force ref update. A committed change can still have an unsuccessful readback receipt; inspect committed, commit_sha, and each verified field before deciding what happened. Do not blindly retry an uncertain write.

• Branch deletion has an unavoidable final-read-to-delete race because GitHub's delete-ref API has no atomic expected-SHA condition. Its checks do not make deletion race-free.

• Both endpoint limiters are configured at 60 requests per 60 seconds. This is a Cloudflare binding limit, not a promise of globally exact throttling or a substitute for GitHub quotas.

• Code-index search is not commit-pinned and is not proof of repository-wide absence. Large listings fail explicitly instead of silently returning a complete-looking partial list.

See protocol details for exact ranges, budgets, errors, and integrity fields. Test results describe the tested implementation and fixtures; they do not establish an uptime or compatibility guarantee for a hosted deployment.

Development and license

See CONTRIBUTING.md for local checks and SECURITY.md for deployment boundaries and reporting guidance. Licensed under the MIT License.