How to Integrate the MCP Server with Cursor: Complete Setup Guide

You can integrate the GitHub MCP Server with Cursor by adding an MCP server entry to your mcp.json configuration file, using either a remote URL with a Personal Access Token or a local Docker container.

The github/github-mcp-server repository provides a Model Context Protocol (MCP) implementation that exposes GitHub's API as AI-consumable tools. When you integrate the MCP server with Cursor, you enable AI-driven GitHub operations—such as repository browsing, issue creation, and pull request management—directly within your editor's chat interface.

Architecture Overview

The integration relies on three core components working together:

1. MCP Server – Runs as either a Docker container (ghcr.io/github/github-mcp-server) or a compiled binary. The server authenticates to GitHub using a Personal Access Token (PAT) and exposes tools via JSON-RPC. In cmd/github-mcp-server/main.go, the main() function parses CLI flags using Cobra and environment variables via Viper, then launches either an HTTP or stdio server.

2. Cursor IDE – Loads MCP configurations from ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-local). Each entry in the mcpServers map defines how Cursor connects to the server—either via HTTP URL or by executing a local command.

3. Communication Path – Cursor v0.48+ supports Streamable HTTP, allowing large payloads to stream without memory buffering. The server registers its tool catalog at startup (generated via GenerateToolsetsHelp() in pkg/github/toolsets.go) and handles requests through RunHTTPServer() in internal/ghmcp/server.go.

Prerequisites

Before you integrate the MCP server with Cursor, ensure you have:

• Cursor v0.48 or later (required for Streamable HTTP support)
• A GitHub Personal Access Token with appropriate scopes (repo, read:org, workflow minimum)
• Docker (if running the server locally) or network access to a remote MCP endpoint

Configuration Methods

You can connect Cursor to the GitHub MCP Server using three distinct approaches: remote hosted, local Docker, or manual HTTP server.

Remote Server Configuration

The simplest method uses GitHub's hosted MCP endpoint. Add this configuration to your mcp.json:

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

Replace YOUR_GITHUB_PAT with your Personal Access Token. Cursor will route all GitHub tool calls to this remote endpoint.

Local Docker Configuration

For offline use or custom toolsets, run the server locally via Docker:

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
      }
    }
  }
}

This configuration tells Cursor to spawn the Docker container on demand. The -i flag enables interactive mode for stdio communication, while --rm cleans up the container after Cursor closes the connection.

Manual HTTP Server (Optional)

For debugging or custom deployments, start the server manually:

# Pull the image

docker pull ghcr.io/github/github-mcp-server

# Run HTTP server on port 8082

docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_GITHUB_PAT \
  -p 8082:8082 \
  ghcr.io/github/github-mcp-server \
  http --port 8082

Then configure Cursor to connect to http://localhost:8082/ without the command/args fields.

Step-by-Step Integration

Follow these steps to complete the integration:

Creating the mcp.json File

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Navigate to Tools & Integrations → MCP Tools
3. Click "Open Config File" or manually create ~/.cursor/mcp.json
4. Paste either the Remote or Local Docker configuration from above
5. Save the file

Verifying the Connection

1. Restart Cursor to reload the MCP configuration
2. Open a chat window (Cmd/Ctrl + L)
3. Look for a green dot next to "GitHub" in the tool selector dropdown
4. Test with: List my GitHub repositories
5. Cursor should invoke the list_repos tool and display your repositories

If the tool fails, check Cursor logs (Help → Show Logs) for "MCP" entries to diagnose authentication or connectivity issues.

Key Implementation Files

Understanding these source files helps troubleshoot advanced configurations:

File	Purpose
cmd/github-mcp-server/main.go	CLI entry point that parses flags via Cobra and environment variables via Viper, then launches the HTTP or stdio server (source)
docs/installation-guides/install-cursor.md	Official Cursor-specific installation documentation (source)
pkg/github/toolsets.go	Contains GenerateToolsetsHelp() which enumerates available toolsets for the --toolsets flag (source)
internal/ghmcp/server.go	Implements RunHTTPServer() which handles JSON-RPC routing and tool registration (source)

Summary

• Integrate the MCP server with Cursor by adding a server entry to ~/.cursor/mcp.json using either a remote URL or local Docker command.
• The GitHub MCP Server (ghcr.io/github/github-mcp-server) authenticates via GITHUB_PERSONAL_ACCESS_TOKEN and exposes GitHub API tools through JSON-RPC.
• Cursor v0.48+ supports Streamable HTTP for efficient payload handling, configured in cmd/github-mcp-server/main.go and served via internal/ghmcp/server.go.
• Verify integration by checking for the green status indicator in Cursor's MCP Tools settings and testing with natural language commands like "List my repositories".

Frequently Asked Questions

What is the difference between remote and local MCP server configurations?

Remote configurations connect Cursor to GitHub's hosted endpoint (https://api.githubcopilot.com/mcp/), requiring only a Personal Access Token and an internet connection. Local configurations run the ghcr.io/github/github-mcp-server Docker container on your machine, offering offline capability and custom toolset restrictions but requiring Docker installation and local resources.

How do I troubleshoot when Cursor shows a red dot instead of green for the GitHub MCP server?

A red indicator typically indicates authentication failure or connectivity issues. First, verify your GITHUB_PERSONAL_ACCESS_TOKEN is valid and has the required scopes (repo, read:org). Check Cursor's logs via Help → Show Logs and search for "MCP" entries. If using Docker, ensure the container can start manually with docker run and that port 8082 is available if running in HTTP mode.

Can I limit which GitHub tools are available to Cursor?

Yes, the GitHub MCP Server supports toolset filtering via the --toolsets flag or toolsets environment variable. When running locally, pass specific toolset names to restrict available functionality (e.g., issues, repos, pull_requests). The GenerateToolsetsHelp() function in pkg/github/toolsets.go enumerates available options. Remote configurations may have predefined toolsets based on your GitHub Copilot subscription tier.

Where does Cursor store the MCP configuration file?

Cursor reads MCP settings from ~/.cursor/mcp.json for global configuration applied to all projects, or from .cursor/mcp.json within your project root for repository-specific settings. The file must contain a top-level mcpServers object containing your GitHub server configuration. Changes require a Cursor restart to take effect.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}