Cursor IDE MCP Setup Guide (2026)

Cursor's MCP integration lets your AI assistant connect to real tools — databases, GitHub, file systems, and APIs — instead of just reading your open files. This guide covers everything: where to find the config file, how to add servers, and how to fix the most common errors.

Where Is the Cursor MCP Config File?

This is the most common question, so let's answer it first.

Cursor stores MCP configuration in a file called mcp.json inside the .cursor directory in your home folder. The exact path depends on your operating system:

| OS | Config File Path |
|----|-----------------|
| macOS | ~/.cursor/mcp.json |
| Windows | %USERPROFILE%\.cursor\mcp.json |
| Linux | ~/.cursor/mcp.json |

To open it directly:

macOS / Linux

open ~/.cursor/mcp.json
or edit with VS Code

code ~/.cursor/mcp.json
Windows (PowerShell)

notepad "$env:USERPROFILE\.cursor\mcp.json"

To open it from inside Cursor:

1. Press Cmd/Ctrl + Shift + P to open the command palette
2. Type Open MCP Settings and select it
3. Cursor opens mcp.json directly in the editor

Note: If the .cursor folder or mcp.json doesn't exist yet, create it. Cursor will pick it up on the next restart.

> Project-scoped vs global config: You can also place an mcp.json inside a specific project's .cursor/ folder. Project-level config takes precedence over the global config for that workspace. Global config (in your home directory) applies everywhere.

---

Prerequisites

Before adding any MCP servers:

---

The mcp.json File Format

The config file uses a straightforward JSON structure:

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

Each key inside mcpServers is a label you choose — it's what Cursor calls the server internally. You can add as many servers as you need.

---

Quick Start: Add GitHub MCP in 3 Minutes

GitHub is the most useful first MCP server for most developers. It lets Cursor read issues, PRs, and repo structure.

Step 1: Get a GitHub Personal Access Token

Step 2: Open your ~/.cursor/mcp.json and add:

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

Step 3: Restart Cursor completely (quit and reopen — not just reload window)

Step 4: Open Cursor chat (Cmd/Ctrl + L) and try:

---

Popular MCP Servers and Their Configs

PostgreSQL / Database

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

Try asking: "Show me all users who signed up in the last 30 days"

Filesystem (Full Project Access)

Gives Cursor read access to any directory — useful for large codebases or mono-repos.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/projects/my-app"
      ]
    }
  }
}

Try asking: "Find all files that import the AuthService"

Context7 (Up-to-date Library Docs)

Context7 fetches current documentation for any library directly into Cursor's context — no more hallucinated APIs.

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

Try asking: "Use context7 to get the latest Next.js 15 App Router docs"

Atlassian (Jira + Confluence)

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@atlassian/mcp-atlassian"],
      "env": {
        "ATLASSIAN_API_TOKEN": "your_api_token",
        "ATLASSIAN_SITE_URL": "https://yourcompany.atlassian.net",
        "ATLASSIAN_USER_EMAIL": "you@company.com"
      }
    }
  }
}

Try asking: "What Jira tickets are assigned to me?" or "Find the API documentation page in Confluence"

Brave Web Search

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

Try asking: "Search for the current rate limits for OpenAI's API"

---

Running Multiple MCP Servers

You can run as many servers as you want simultaneously. Just add each one as a key in mcpServers:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://..."
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/your/project"]
    }
  }
}

Cursor starts each server in a separate process. Servers that fail to start don't affect the others.

---

Using the cwd Field

Some servers need to know which directory to treat as the working directory:

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "/Users/you/projects/my-mcp-server"
    }
  }
}

This is important when the server script uses relative file paths internally.

---

Troubleshooting Common Errors

"MCP server not found" or server doesn't appear in Cursor

1. Check your JSON is valid — use jsonlint.com to paste and validate
2. Use absolute paths in args and cwd, not ~/ shortcuts (Cursor may not expand them)
3. Fully restart Cursor — closing the window isn't always enough; quit from the menu bar
4. Check that npx is in your PATH — run which npx in terminal; if blank, reinstall Node.js

"Tool not available" in Cursor chat

Server starts but gives wrong data / stale responses

Environment variables not loading

If your server needs API keys, put them directly in the env block rather than relying on your shell's .env or .bashrc — Cursor doesn't always inherit shell environment variables.

{
  "env": {
    "MY_API_KEY": "actual-key-value-here"
  }
}

---

Build a Custom MCP Server

If you need a server that doesn't exist yet, building one is straightforward.

from mcp.server import Server
from mcp.types import Tool
app = Server("my-custom-server")
@app.tool()
async def search_internal_docs(query: str) -> str:
    """Search your company's internal documentation.
    
    Args:
        query: What to search for
    
    Returns:
        Relevant documentation excerpts
    """
    # Your search logic here
    results = my_search_function(query)
    return "\n".join(results)
if __name__ == "__main__":
    import asyncio
    asyncio.run(app.run_stdio())

Install the SDK: pip install mcp

The docstring is what Cursor's AI reads to understand when and how to use the tool — write it like you're explaining to a smart colleague who doesn't know your codebase.

---

Quick Reference

| Task | How |
|------|-----|
| Find config file | ~/.cursor/mcp.json (global) or .cursor/mcp.json (project) |
| Open config in Cursor | Cmd/Ctrl + Shift + P → "Open MCP Settings" |
| Apply config changes | Fully restart Cursor |
| Check server status | View → Output → MCP |
| Test a server manually | Run the command + args in your terminal |
| Add API keys | Use the env block in config, not shell environment |

---

Related Guides