ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Connect GitHub MCP to Cursor

Connect GitHub’s hosted MCP server to Cursor with a PAT, project or global config, verification steps, local Docker option, and fixes for common errors.

By the ScreenshotNeo team1 October 20267 min read

Use GitHub’s hosted MCP server in Cursor. Add https://api.githubcopilot.com/mcp/ to Cursor’s MCP configuration, authenticate it with a GitHub personal access token (PAT), restart Cursor, and verify that GitHub tools appear in chat.

GitHub’s Cursor-specific instructions currently call for PAT authentication for this hosted server. Cursor supports OAuth for some MCP servers, but that does not mean OAuth is the authentication method for GitHub’s server.

What you need

  • Cursor with MCP support. GitHub’s guide identifies Cursor 0.48.0 or newer for Streamable HTTP; check the current GitHub and Cursor documentation before relying on that version number.
  • A GitHub PAT with only the permissions needed for the repositories and actions you want Cursor to use.
  • Access to edit either your global Cursor configuration or a project’s .cursor/mcp.json.

Keep the PAT private. Do not commit it to a repository, paste it into a shared project configuration, or include it in screenshots, support tickets, or logs.

1. Choose the configuration scope

Use ~/.cursor/mcp.json when you want GitHub tools available in all Cursor projects. Use .cursor/mcp.json inside a project when only that project should expose the server.

Location Best for Security consideration
~/.cursor/mcp.json Personal, global access Every Cursor project can use the configured GitHub server.
.cursor/mcp.json One repository or team workflow Keep the file private if it contains a token; prefer an environment or secret mechanism supported by your setup.

2. Add the GitHub server entry

Create or edit the selected file. The server must be nested under mcpServers and the file must remain valid JSON.

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_PAT"
      }
    }
  }
}

Replace YOUR_GITHUB_PAT with your token. Use a token scoped to the repositories and operations you actually need. If your organization controls token policies, follow those policies even when they are more restrictive than the default GitHub setup.

3. Save the file and restart Cursor

Cursor reads MCP configuration when it starts. Save the JSON, fully quit and reopen Cursor, then open Cursor’s MCP settings.

4. Confirm the connection

  1. Open Cursor’s MCP tools or integrations settings.
  2. Confirm that the github server is listed and connected.
  3. Open a chat that can use MCP tools.
  4. Ask: List my GitHub repositories.
  5. Confirm that the returned repositories match the access granted to the PAT.

If the server appears in settings but no tools are available in chat, restart Cursor again and inspect the connection status. Also check that the file you edited is the scope you intended and that there is only one conflicting github entry.

Using GitHub MCP safely

Limit the token

Grant the smallest set of permissions that supports the work. A token used only to inspect selected repositories should not automatically have permission to modify unrelated repositories or administrative settings.

Review actions before approving them

MCP tools can access external services and execute actions on your behalf. Read the tool name, repository, branch, issue, pull request, or file path before approving an operation. Treat an MCP server as code with access to your account.

Keep secrets out of shared configuration

A project-level file can be copied, committed, or uploaded accidentally. Add local MCP configuration to the repository’s ignore rules when appropriate, and rotate the PAT immediately if it is exposed.

Hosted server versus local Docker server

The hosted endpoint is GitHub’s simplest documented route for Cursor. GitHub hosts the service, so you do not need to run a local MCP process.

A local alternative runs the official GitHub MCP Server through Docker. Choose it when your organization requires local execution or when you need control over where the MCP process runs. It adds operational work: Docker Desktop must be installed and running, the official image must be available, and you must maintain the local process and its authentication.

Choice Advantages Trade-offs
Hosted GitHub endpoint Fastest setup; no local server process Depends on access to GitHub’s hosted endpoint and your network policy
Local Docker server Local runtime control; useful where hosted services are restricted Requires Docker Desktop, image management, process maintenance, and local authentication setup

GitHub documents PAT authentication for the Cursor hosted setup. Its repository also documents local authentication options, including PAT use and OAuth-based login where supported. Follow the authentication instructions for the exact deployment you choose.

Troubleshooting

“Authentication failed” or unauthorized responses

Cause: The PAT is invalid, expired, malformed, or lacks access to the requested repository or action.

Fix: Create or rotate a valid token, copy it without extra spaces, confirm the Bearer prefix, and grant only the permissions required for the operation. Test with a repository the token can access.

The GitHub server does not appear in Cursor

Cause: Cursor loaded a different configuration path, the JSON is invalid, or Cursor was not restarted.

Fix: Validate the JSON, check whether you edited ~/.cursor/mcp.json or the project’s .cursor/mcp.json, restart Cursor completely, and inspect MCP settings for a connection error.

The server is connected but tools are missing from chat

Cause: The chat context has not refreshed, or the server failed during tool discovery.

Fix: Start a new chat, restart Cursor, and check the MCP status panel. Remove duplicate server entries and confirm the endpoint includes the trailing slash shown in GitHub’s configuration.

Remote connection or timeout errors

Cause: A firewall, proxy, VPN, DNS policy, or organization network rule is blocking the hosted endpoint.

Fix: Check network and proxy settings, allow access to api.githubcopilot.com if permitted by your organization, and retry outside the restricted network to isolate the cause.

Docker setup cannot start

Cause: Docker Desktop is not running, the image cannot be pulled, or the local server configuration is incomplete.

Fix: Start Docker Desktop, verify that the official GitHub MCP image can be pulled, then compare the local configuration with GitHub’s repository instructions. Check container logs for authentication and port errors.

JSON parse errors

Cause: A trailing comma, unescaped quote, missing brace, or incorrect nesting under mcpServers.

Fix: Run the file through a JSON validator and reduce it to the minimal configuration shown above before adding other servers.

Performance, reliability, and cost considerations

  • Latency: The hosted path adds network round trips between Cursor, GitHub’s MCP endpoint, and GitHub APIs. Large repository searches and multi-step actions take longer than a single metadata request.
  • Reliability: Your workflow depends on Cursor, the hosted MCP endpoint, GitHub API availability, authentication validity, and your network. Keep important changes reviewable and do not assume a failed tool call completed an action.
  • Rate limits: GitHub API limits and token permissions still apply. Narrow repository searches and avoid repeatedly asking an agent to fetch the same large result set.
  • Cost: Cursor, GitHub, and any token or organization limits are governed by their own plans and policies. The dossier does not establish a separate MCP server fee.
  • Local operations: Docker avoids dependence on a hosted MCP process but shifts maintenance, updates, uptime, and resource usage to your machine or infrastructure.

Or skip the browser setup

If your goal is to give an AI agent clean screenshots of web pages while it works in Cursor, ScreenshotNeo provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools. It removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; and every response reports its verdict and billing status.

One request returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for all options.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const data = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', data);

ScreenshotNeo includes full-page capture with lazy images loaded, CSS-selector element capture, device presets and custom viewports, dark mode, retina scale, custom CSS and JavaScript, waits, request blocking, headers, cookies, user agents, geolocation, caching, signed links, asynchronous jobs, bulk capture, PDF options, usage reporting, and an OpenAPI specification. One thousand screenshots per month are free with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

FAQ

Can I use Cursor’s OAuth flow instead of a PAT?

Not for the hosted GitHub setup described here. GitHub’s Cursor-specific guide currently specifies a PAT. Cursor’s general OAuth support applies only to servers that support that authentication method.

Should I configure GitHub MCP globally or per project?

Use the global file for personal access across projects. Use the project file when the server should be available only in one repository or workflow.

No. Docker is required only for the local GitHub MCP Server alternative.

How do I revoke access?

Revoke or rotate the PAT in GitHub, remove the MCP entry from Cursor, then restart Cursor so the old connection is discarded.

Keep reading