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

> Integrate the MCP Server with Cursor easily. Follow our complete setup guide for remote URL or local Docker container integration, ensuring seamless workflow.

- Repository: [GitHub/github-mcp-server](https://github.com/github/github-mcp-server)
- Tags: how-to-guide
- Published: 2026-02-16

---

**You can integrate the GitHub MCP Server with Cursor by adding an MCP server entry to your [`mcp.json`](https://github.com/github/github-mcp-server/blob/main/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`](https://github.com/github/github-mcp-server/blob/main/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`](https://github.com/github/github-mcp-server/blob/main/.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`](https://github.com/github/github-mcp-server/blob/main/pkg/github/toolsets.go)) and handles requests through `RunHTTPServer()` in [`internal/ghmcp/server.go`](https://github.com/github/github-mcp-server/blob/main/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`](https://github.com/github/github-mcp-server/blob/main/mcp.json):

```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:

```json
{
  "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:

```bash

# 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`](https://github.com/github/github-mcp-server/blob/main/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](https://github.com/github/github-mcp-server/blob/main/cmd/github-mcp-server/main.go)) |
| [`docs/installation-guides/install-cursor.md`](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-cursor.md) | Official Cursor-specific installation documentation ([source](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-cursor.md)) |
| [`pkg/github/toolsets.go`](https://github.com/github/github-mcp-server/blob/main/pkg/github/toolsets.go) | Contains `GenerateToolsetsHelp()` which enumerates available toolsets for the `--toolsets` flag ([source](https://github.com/github/github-mcp-server/search?q=GenerateToolsetsHelp)) |
| [`internal/ghmcp/server.go`](https://github.com/github/github-mcp-server/blob/main/internal/ghmcp/server.go) | Implements `RunHTTPServer()` which handles JSON-RPC routing and tool registration ([source](https://github.com/github/github-mcp-server/search?q=RunHTTPServer)) |

## 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`](https://github.com/github/github-mcp-server/blob/main/cmd/github-mcp-server/main.go) and served via [`internal/ghmcp/server.go`](https://github.com/github/github-mcp-server/blob/main/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`](https://github.com/github/github-mcp-server/blob/main/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`](https://github.com/github/github-mcp-server/blob/main/.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.