Cursor MCP Servers: Complete Setup Guide for 2026

Problem: You want to extend Cursor with external tools and data sources, but the MCP configuration process feels unclear. Where do the files go? What format do they use? How does it compare to Claude Code?

Quick Win: Create a .cursor/mcp.json file in your project root and add your first MCP server:

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": { "BRAVE_API_KEY": "your-api-key" }
    }
  }
}

Restart Cursor, and you now have web search capabilities inside the IDE.

Verified working with Cursor 0.45+ on macOS 14, Windows 11, and Ubuntu 22.04 as of May 2026. All configurations in this guide were tested against the current Cursor stable channel. Cursor versions before 0.45 use a different settings UI; if you're on an older build, update before following along.

What Are Cursor MCP Servers?

Cursor MCP servers connect Cursor's AI to external tools, databases, and APIs through the Model Context Protocol. They work identically to MCP servers in Claude Code and Claude Desktop since they all use the same underlying protocol.

With MCP servers configured, Cursor can:

• Search the web and fetch documentation
• Query databases with natural language
• Interact with GitHub, Slack, and other services
• Automate browser tasks for testing
• Access any service with an MCP server implementation

The MCP ecosystem is shared across all compatible tools. Any MCP server that works with Claude Desktop also works with Cursor.

Setting Up MCP Servers in Cursor

Configuration File Locations

Cursor supports two configuration locations:

Use project-level configs for project-specific tools (like a database server for your app). Use global configs for tools you want everywhere (like web search or GitHub).

Step-by-Step Setup

Method 1: Manual Configuration

1. Create the config file at .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)
2. Add your MCP server configuration
3. Restart Cursor to load the new servers
4. Test by asking the AI to use a tool from your server

Method 2: Command Palette

1. Open Command Palette (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows)
2. Search for "MCP" and select "View: Open MCP Settings"
3. Click "New MCP Server" under MCP Tools
4. Cursor creates and opens the mcp.json file for editing

Configuration Format

Cursor MCP servers use the same JSON format as Claude Desktop:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-name"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

For Python-based MCP servers:

{
  "mcpServers": {
    "python-server": {
      "command": "python",
      "args": ["path/to/server.py"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/mydb"
      }
    }
  }
}

Remote Server Configuration

Cursor also supports remote MCP servers via HTTP:

{
  "mcpServers": {
    "remote-server": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

This enables connecting to MCP servers running on remote machines or as shared services. Cursor's HTTP and SSE transports handle reconnection automatically; if the remote server restarts, Cursor reconnects on the next tool invocation.

Best MCP Servers for Cursor

These Cursor MCP servers provide the highest-impact capabilities. All configurations work directly in your .cursor/mcp.json. Each entry below shows the config plus what it actually unlocks in your day-to-day workflow.

Web Search and Research

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": { "BRAVE_API_KEY": "your-key" }
    }
  }
}

What you can do: Ask Cursor to look up current API docs mid-conversation, find a Stack Overflow thread for an obscure error, or pull the latest changelog for a dependency without leaving the editor.

GitHub Integration

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "your-token" }
    }
  }
}

What you can do: Open and triage issues, comment on pull requests, fetch the diff from another branch for review, or generate release notes from the last 20 merged PRs without context-switching to the GitHub UI.

Database Access

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "postgresql://user:pass@localhost/db" }
    }
  }
}

What you can do: Ask Cursor to inspect your schema, write a query against a real table, run EXPLAIN ANALYZE, and debug a failing migration against a copy of your dev database.

Browser Automation

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

What you can do: Have Cursor open a page, click through a flow, screenshot the result, and write a Playwright test that reproduces the steps. See our browser automation guide for advanced patterns.

File Operations

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/directory"
      ]
    }
  }
}

What you can do: Give Cursor scoped read/write access to directories outside the open workspace — useful for cross-repo refactors or pulling assets from a sibling project without opening it.

Memory and Knowledge

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

What you can do: Persist project decisions, glossary terms, or architectural notes across Cursor sessions in a knowledge graph that the AI can query later.

Browse our complete MCP servers list for 50+ additional options.

Two vendor MCPs worth noting for Cursor users: Shopify AI Toolkit and Higgsfield MCP both support Cursor's .cursor/mcp.json config format and work without modification. If you already run these with Claude Code, the same config block copies over directly.

Cursor vs Claude Code MCP

Cursor and Claude Code both speak the same Model Context Protocol, so server packages are interchangeable. The differences are in transport, configuration ergonomics, and context handling.

When to Use Cursor MCP vs Claude Code MCP

The two tools optimize for different workflows.

Cursor MCP shines when:

• You want full IDE features (multi-cursor edits, inline suggestions, refactor menus) alongside MCP-powered AI
• Your team is already standardized on Cursor and you want to bolt on MCP without changing IDEs
• You need OAuth-authenticated services (GitHub, Notion, Linear) and don't want to manage API tokens manually
• Your MCP servers are small in number and the all-load-at-start overhead doesn't matter

Claude Code MCP shines when:

• You're working in the terminal and want a leaner, faster context loop
• You have many MCP servers and need tool search lazy loading to keep context lean (the all-load-at-start cost in Cursor adds up fast past ~10 servers)
• You're orchestrating multi-agent or multi-session workflows where the terminal is a better surface than an IDE
• You want resources support (read-only file/data exposure to the model) for grounding without tool calls

A practical pattern: many developers run both. Cursor handles the IDE-bound work where inline suggestions and refactors matter. Claude Code handles the long-running orchestration, batch refactors, and any session that involves more than a handful of MCP servers.

Both support the same server packages. A server configured for Claude Desktop works in Cursor and vice versa. This portability is worth noting: if you use a starterkit like ClaudeFast's Code Kit with Claude Code, the MCP configurations it ships carry over to Cursor projects with minimal adjustment.

Troubleshooting Cursor MCP Servers

These are the failure modes that come up most often, the actual error messages they produce, and the fixes that work.

MCP Tools Not Enabled in Settings

Symptom: You added a server to .cursor/mcp.json, restarted Cursor, but the AI says it has no tools available.

Likely cause: Cursor's MCP feature is gated behind a settings toggle that defaults to off in some installs.

Fix: Open Cursor Settings (Cmd/Ctrl + ,), search for "MCP", and confirm "Enable MCP Servers" is checked. Then restart Cursor. From the Command Palette, run MCP: View Server Status to confirm your servers loaded.

Server Not Loading (No Errors)

Symptom: MCP server doesn't appear in available tools, no obvious error.

Fix:

1. Verify the JSON syntax is valid (no trailing commas, no comments — JSON does not support either)
2. Restart Cursor completely (Quit and relaunch, not just reload window)
3. Check the Output panel: View > Output > select "MCP" from the dropdown to see load errors
4. On macOS, check ~/Library/Logs/Cursor/ for mcp-*.log files; on Windows, %APPDATA%\Cursor\logs\; on Linux, ~/.config/Cursor/logs/

Authentication Failed

Symptom: Server loads but API calls fail with "401 Unauthorized" or "Invalid token".

Fix: Verify environment variables are set correctly:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}

Use ${env:VAR_NAME} to reference system environment variables instead of hardcoding secrets. If ${env:VAR_NAME} resolves to empty, your shell environment isn't being inherited — set the variable in your OS-level environment (System Properties on Windows, .zshrc/.bash_profile on macOS/Linux), then restart Cursor so it picks up the new value.

npx Command Not Found

Symptom: Server fails with Error: spawn npx ENOENT in the MCP output panel.

Fix: Cursor sometimes doesn't inherit your shell's PATH, especially when launched from the GUI on macOS. Either install Node.js via the official installer (which sets a system-wide PATH), or use the full path to npx in your config:

{
  "mcpServers": {
    "server-name": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-name"]
    }
  }
}

Find your npx path by running which npx (macOS/Linux) or where npx (Windows) in your terminal.

Windows Path Quoting Issues

Symptom: On Windows, server fails with errors like 'C:\Users\You\AppData\Roaming\npm\npx.cmd' is not recognized or paths get truncated at spaces.

Fix: Windows paths with spaces (Program Files, user folders with spaces) need to be wrapped or escaped. In JSON, escape backslashes:

{
  "mcpServers": {
    "filesystem": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\You\\projects\\my-app"
      ]
    }
  }
}

Use npx.cmd (not bare npx) on Windows. The .cmd extension matters for spawn calls.

Remote Server Connection Issues

Symptom: HTTP-based MCP server fails to connect with ECONNREFUSED or "tools list timed out".

Fix:

1. Verify the server is running and accessible from the same machine: curl http://localhost:3000/mcp should return something
2. Check firewall rules allow the connection on the relevant port
3. Ensure the URL includes the correct protocol (http:// for local, https:// for remote)
4. If using SSE transport, confirm the server actually supports SSE (some HTTP servers don't)

Tools Show Up But Don't Run

Symptom: Cursor lists the MCP server's tools, but invoking one returns "Tool execution failed" with no specifics.

Fix: Check the MCP output panel for the underlying stack trace. The two most common causes:

1. Missing required environment variable that the server needs at tool-invocation time (not just at startup). Set it explicitly in the env block.
2. Permission denied on a file or socket the tool tries to access. Run Cursor with the same user that owns the target resource, or chmod the resource appropriately.

Server Quietly Crashes Mid-Session

Symptom: Tools worked at the start of the session but stopped responding partway through.

Fix: Some MCP servers leak memory or fail when their upstream API rate-limits them. Restart Cursor to relaunch the server process. For a permanent fix, file an issue with the server author and pin to a known-good version of the package by replacing npx -y @scope/server with a specific version tag (for example npx -y @scope/server@<version> where <version> is a known-good release like 1.2.3).

Next Steps

Expand your Cursor MCP setup:

1. Start simple: Configure Brave Search for immediate web access
2. Add development tools: GitHub and database servers accelerate coding workflows
3. Explore automation: Set up browser automation for testing
4. Build custom servers: See our guide on building custom MCP integrations for your specific APIs and tools
5. Browse all options: Check the complete MCP servers list

Cursor MCP servers transform the IDE from an isolated editor into a connected development environment. Start with one server, prove the value, then expand as your workflow demands.

Sources:

• Cursor MCP Documentation
• Model Context Protocol Specification