Github

This MCP server enables remote connections via GitHub OAuth, letting users sign in with GitHub to access tools securely and connect clients that support the MCP protocol.

How to use

You connect to the remote MCP server using an MCP client or the Inspector to verify tools. After you configure GitHub OAuth, authenticated users can access available tools like add and userInfoOctokit. The generateImage tool is restricted to specific GitHub usernames listed in your configuration. When you sign in, the server maintains your authentication state and controls tool availability based on your identity.

How to install

Prerequisites: you need Node.js and Wrangler installed. You also need a GitHub account to create an OAuth App.

1. Install dependencies or create the MCP server project using the provided template.

npm install

npm create cloudflare@latest -- my-mcp-server --template=cloudflare/ai/demos/remote-mcp-github-oauth

2. On GitHub, create a new OAuth App and configure the URLs.

• Homepage URL: https://mcp-github-oauth.<your-subdomain>.workers.dev
• Authorization callback URL: https://mcp-github-oauth.<your-subdomain>.workers.dev/callback
• Save your Client ID and generate a Client Secret.

3. Store secrets on the local environment or in Cloudflare Workers' secrets store.

wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY # add any random string here e.g. openssl rand -hex 32

4. Create and configure the KV namespace used for OAuth state.

wrangler kv:namespace create "OAUTH_KV"

Update the Wrangler configuration with the KV namespace ID as required by your setup.

5) Deploy the MCP server so it becomes available at your workers.dev domain.

wrangler deploy

6) Test the remote server using the Inspector to confirm the SSE endpoint is reachable.

npx @modelcontextprotocol/inspector@latest

Enter `https://mcp-github-oauth.<your-subdomain>.workers.dev/sse` and connect. After authentication, you should see the Tools listed and usable.

Access control

This MCP server uses GitHub OAuth for authentication. All authenticated GitHub users can access basic tools like add and userInfoOctokit. The generateImage tool is restricted to specific GitHub usernames defined in your configuration.

// Add GitHub usernames for image generation access
const ALLOWED_USERNAMES = new Set([
  'yourusername',
  'teammate1'
]);

Access the remote MCP server from Claude Desktop

Open Claude Desktop and go to Settings -> Developer -> Edit Config. Replace the content with the following MCP server configuration. After you restart Claude Desktop, a browser window opens for GitHub login. Complete the flow to grant Claude access and enable the tools.

{
  "mcpServers": {
    "math": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp-github-oauth.<your-subdomain>.workers.dev/sse"
      ]
    }
  }
}

For Local Development

To iterate locally, you’ll create a separate GitHub OAuth App for localhost use and run the server with a local dev command.

Local OAuth App setup

Homepage URL: http://localhost:8788
Authorization callback URL: http://localhost:8788/callback

Create a .dev.vars file in your project root with these values.

GITHUB_CLIENT_ID=your_development_github_client_id
GITHUB_CLIENT_SECRET=your_development_github_client_secret

Run the server locally and test the SSE endpoint.

wrangler dev

To test the local server, open http://localhost:8788/sse in the Inspector and follow prompts to authenticate. After authentication, you can list and use tools.

Using Claude and other MCP Clients

When Claude does not support remote MCP servers directly, you can still verify connectivity by checking the Tools in Claude once authentication is complete. Hover over the tools area to confirm availability.

Using Cursor and other MCP Clients

To connect Cursor, choose Type: Command and combine command and args into one string, for example: npx mcp-remote https://<your-worker-name>.<your-subdomain>.workers.dev/sse. Note that HTTP+SSE servers work with authentication through the mcp-remote flow.

How it works behind the scenes

OAuth Provider handles the OAuth 2.1 flow, issuing and validating tokens, and securely storing state in KV storage. Durable MCP provides persistent state and user context, while MCP Remote defines the tool protocol and ensures proper serialization for client calls.

Available tools

add

Adds two numbers or combines values according to the MCP protocol, used for simple arithmetic or data operations.

userInfoOctokit

Fetches information about the authenticated GitHub user using Octokit-compatible tooling.

generateImage

Generates an image based on prompts. Access is restricted to usernames listed in ALLOWED_USERNAMES.