Cursor MCP Server Setup: The Complete Guide (2026)

Quick Start

MCP (Model Context Protocol) lets Cursor's agent call external tools directly: query databases, fetch documentation, run browser tests, search code semantically. Instead of pasting context into prompts, the agent uses MCP tools on its own.

Config File Locations

Cursor reads MCP configuration from two locations. Use project-level config for servers specific to a codebase (database connections, project-specific APIs). Use global config for servers you want everywhere (documentation, code search, GitHub).

Project-level config takes precedence. If the same server name appears in both files, the project-level config wins. This lets you override global settings per project (e.g., different GitHub tokens for work vs personal repos).

Adding MCP Servers via the Cursor UI

If you prefer not to edit JSON files, Cursor has a built-in UI for adding MCP servers.

Method 1: Settings Panel

1. Open Cursor Settings (Cmd+, on macOS, Ctrl+, on Windows/Linux)
2. Navigate to Tools & MCP
3. Click + New MCP Server
4. Fill in the Name, Transport Type (stdio, sse, or streamable-http), and Command (for stdio) or URL (for sse/http)
5. Click Save

Method 2: Command Palette

1. Press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)
2. Type "MCP" and select MCP: Add Server
3. Follow the prompts

Method 3: One-Click Install

Many MCP servers have an "Add to Cursor" button on their documentation pages. Clicking it opens Cursor with the server name, transport, and command pre-filled. You just confirm and save.

JSON Configuration Format

The config file is a JSON object with a single mcpServers key. Each server entry has a name (the key) and a configuration object specifying how to launch or connect to the server.

Stdio Server (Local Process)

The most common type. Cursor starts the process and communicates through stdin/stdout.

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp-server"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y", "@modelcontextprotocol/server-filesystem",
        "/Users/you/projects",
        "/Users/you/documents"
      ]
    }
  }
}

SSE Server (Remote)

For servers running on a remote machine or shared team server. Cursor connects over HTTP with streaming.

{
  "mcpServers": {
    "remote-db": {
      "url": "http://localhost:3001/sse",
      "transport": "sse"
    }
  }
}

Streamable HTTP Server

Stateless HTTP transport. Simpler than SSE for remote deployments where you don't need streaming.

{
  "mcpServers": {
    "team-tools": {
      "url": "https://mcp.yourcompany.com/tools",
      "transport": "streamable-http"
    }
  }
}

Python-Based Servers

Some MCP servers are Python packages. Use uvx (from the uv package manager) or python -m to run them.

{
  "mcpServers": {
    "my-python-server": {
      "command": "uvx",
      "args": ["my-mcp-server"]
    }
  }
}

Transport Types

Use stdio unless you have a specific reason not to. It is simpler, requires no network setup, and Cursor manages the server lifecycle (starts on open, stops on close). SSE and Streamable HTTP are for teams sharing a central MCP server or connecting to remote services.

Top MCP Servers for Cursor

The MCP ecosystem has 1,800+ servers. Most are irrelevant to coding. These are the ones that measurably improve Cursor's agent workflows, ranked by impact.

1. Context7 (Documentation)

Fetches version-specific library documentation and injects it into the agent's context. Without this, the model generates code against APIs from its training data, which may be months or years out of date. Context7 is the single highest-impact MCP server for code quality.

"context7": {
  "command": "npx",
  "args": ["-y", "@context7/mcp-server"]
}

2. GitHub MCP (Version Control)

Full GitHub API access from within Cursor: read PR diffs, post review comments, create issues, check CI status, search code across repos. The most widely used MCP server across all AI coding tools.

"github": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
  }
}

3. Playwright MCP (Browser Testing)

Lets the agent interact with web pages: navigate, click, fill forms, verify UI state. Uses accessibility snapshots instead of screenshots, keeping context token cost low. Essential for frontend development workflows.

"playwright": {
  "command": "npx",
  "args": ["-y", "@anthropic/mcp-playwright"]
}

4. Supabase MCP (Database)

20+ tools including table design, migrations, SQL queries, database branching, and TypeScript type generation. Combines Postgres, auth, and storage access in one server.

"supabase": {
  "command": "npx",
  "args": ["-y", "@supabase/mcp-server"],
  "env": {
    "SUPABASE_ACCESS_TOKEN": "sbp_your_token"
  }
}

5. Filesystem MCP (Scoped File Access)

The official Anthropic filesystem server with security boundaries. Limits access to specified directories only. Useful when you want the agent to read code in specific paths without full filesystem access.

6. Desktop Commander (Terminal)

Terminal command execution with process management. The agent can start dev servers, run builds, kill processes, and manage background tasks. Adds diff-based file editing for large files. More useful in Cursor than in Claude Code (which has built-in terminal access).

7. Figma MCP (Design-to-Code)

Figma's official MCP server exposes the live structure of selected Figma layers: hierarchy, auto-layout, variants, text styles, and spacing tokens. The agent generates code against the actual design specification, not a screenshot interpretation.

WarpGrep: Semantic Code Search MCP for Cursor

WarpGrep is an MCP server purpose-built for code search. It indexes your entire codebase and lets the agent search by meaning, not just string matching. When a coding agent needs to find "where authentication is handled" or "the function that processes webhook payments," WarpGrep returns the relevant files and code sections in under a second.

This matters because search is the primary bottleneck for AI coding agents. Cognition measured that their agents spend 60% of execution time on search and navigation. Grep and file-tree browsing work for exact strings but fail when the agent needs to understand code relationships.

"warpgrep": {
  "command": "npx",
  "args": ["-y", "@anthropic/warpgrep-mcp"],
  "env": {
    "WARPGREP_API_KEY": "your_api_key"
  }
}

MCP Setup: Cursor vs Claude Code vs Windsurf

All three support MCP, but the setup and maturity differ. If you work across multiple tools, understanding the differences saves time.

Cursor has the largest MCP ecosystem with cursor.directory hosting hundreds of server configs. Claude Code has the most native integration since Anthropic created the protocol. Windsurf added MCP support in early 2026 and has fewer community resources.

The JSON format is nearly identical across all three. If you have a working config for one client, converting it to another takes seconds. The mcpServers object structure, command/args/env fields, and server packages are all the same.

Troubleshooting

"Client Closed" Error

The server process failed to start. Run the exact command from your terminal to see the actual error:

# Copy the command from your mcp.json and run it directly
npx -y @context7/mcp-server

# If it fails, you'll see the actual error (missing dependency, etc.)
# Cursor doesn't show stderr from MCP servers in its logs

Server Shows No Tools

Restart Cursor after any config change. Cursor reads mcp.json on startup. Changes to the file while Cursor is running are not picked up automatically.

Windows: npx Commands Fail

On Windows, npx is a batch script (npx.cmd) that needs cmd.exe to execute. Change your config to use the explicit interpreter:

{
  "mcpServers": {
    "context7": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@context7/mcp-server"]
    }
  }
}

macOS: Command Not Found

Cursor may not inherit your shell's PATH. If npx or node works in your terminal but fails in Cursor, use the full path:

# Find the full path
which npx
# Example output: /opt/homebrew/bin/npx

# Use the full path in mcp.json
{
  "mcpServers": {
    "context7": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@context7/mcp-server"]
    }
  }
}

WSL vs Windows Confusion

If you use WSL, Node.js installed inside WSL is invisible to Cursor (a Windows app). Install Node.js on the Windows side too, or use the Windows npx.cmd path.

Too Many Servers Slowing Down Agent

FAQ

Where is the Cursor MCP config file?

Project-level: .cursor/mcp.json in your project root. Global: ~/.cursor/mcp.json (macOS/Linux) or %USERPROFILE%\.cursor\mcp.json (Windows). Project-level takes precedence if the same server name appears in both.

How do I add an MCP server to Cursor?

Three options: (1) Settings > Tools & MCP > New MCP Server in the UI. (2) Create or edit .cursor/mcp.json manually. (3) Click "Add to Cursor" buttons on MCP server docs pages. After adding, restart Cursor and check for a green dot next to the server name.

What transport types does Cursor support?

Three: stdio (Cursor launches the process, communicates via stdin/stdout), SSE (connects to a remote server over HTTP with streaming), and Streamable HTTP (stateless HTTP requests). Use stdio for local servers. Use SSE or Streamable HTTP for remote/shared servers.

Why does my MCP server show "Client Closed"?

The server process failed to start. Common causes: npx/node not in Cursor's PATH, missing dependencies, wrong package name, or Windows needing cmd /c npx instead of npx directly. Run the command from your terminal to see the actual error.

What are the best MCP servers for Cursor?

Context7 (documentation), GitHub MCP (version control), Playwright (browser testing), Supabase (database), and WarpGrep (semantic code search). Start with 2-3 and add more as needed. See our full MCP server rankings for detailed evaluations.

Does Cursor MCP work with Agent mode?

Yes. MCP tools are available in Agent mode (Cmd+I). The agent discovers and calls MCP tools automatically when relevant. Since January 2026, Cursor uses dynamic context management that reduces token usage by 46.9% when running multiple MCP servers.

Related Guides

• Best MCP Servers for Coding (2026)
• Claude Code MCP Server Setup
• Playwright MCP Guide
• Claude Code vs Cursor
• Best Cursor Alternatives 2026