topmcps
Browse MCPs
Tutorial5 min readMay 5, 2026

How to Install an MCP Server on Cursor

Cursor ships with native MCP support. Drop a server into mcp.json — at the global or project scope — reload the window, and the tools appear in Agent mode. The flow is identical for every MCP server you will ever install in Cursor.

Goal

Connect any MCP server to Cursor

Time

~5 minutes

Prereq

Cursor installed, Node.js for npx-based servers

Steps

1

Pick a scope: global or project

Cursor reads two files. ~/.cursor/mcp.json applies to every workspace you open. .cursor/mcp.json at the root of a repo applies only to that repo and can be committed so your team shares the same MCPs. Use the project file for repo-specific tools (Postgres, internal APIs); use global for personal tools that follow you everywhere.

2

Open or create the file

For global config: open ~/.cursor/mcp.json in your editor (create it if it does not exist). For project config: create .cursor/mcp.json at the root of your repo. Both files use the same JSON shape — the only difference is which scope picks them up.

3

Add an mcpServers block

Each entry is keyed by a name you choose, with command and args fields telling Cursor how to launch the server. The example below adds Context7 (live library docs) and Filesystem scoped to a single directory.

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/code"
      ]
    }
  }
}
4

Set tokens via env

For credentialled servers (GitHub, Supabase, Linear), put tokens in an env block alongside command and args. Add the file to .gitignore if it contains real tokens — committed mcp.json should reference env-only references via your shell, not raw values.

"github": {
  "command": "npx",
  "args": ["@github/github-mcp-server"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
  }
}
5

Reload Cursor and verify in Agent mode

Cmd/Ctrl+Shift+P → "Reload Window" — that is enough; no full quit needed. Open Cursor in Agent mode and the new MCP tools appear in the tool picker. The MCP panel (typically reachable via Settings → MCP) shows each connected server with a green status.

Use project scope for team-shared MCPs

Anything every contributor needs — a Postgres MCP pointed at the dev database, an internal-API MCP, repo-specific tooling — belongs in .cursor/mcp.json at the repo root. Anything personal — your note-taking MCP, local memory — belongs in ~/.cursor/mcp.json. Mixing the two confuses onboarding.

Sample mcp.json

A minimal global config with three popular servers. Drop into ~/.cursor/mcp.json and reload Cursor.

~/.cursor/mcp.json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/code"
      ]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

When it does not work

Reload Window did not pick up the change

Sometimes a cached process holds the old config. Quit Cursor entirely (Cmd+Q) and reopen. If you edited the global file, every workspace gets the change — verify in a fresh window before assuming the edit failed.

.cursor/mcp.json is checked in but no teammates see the server

Confirm the file is at the repo root, not nested. Cursor only auto-discovers .cursor/mcp.json one level deep. Also check teammates pulled the latest commit and reloaded their window after pulling.

Server is listed but the agent never calls it

Open the tool picker in Agent mode and confirm the tools appear. If they do, the issue is prompt-side — the model is not deciding to use them. Try a more explicit prompt ("use the Filesystem MCP to read this file"). If they do not appear, the server failed to expose its manifest — check the server logs.

FAQ

Where does Cursor store its MCP config?

Two paths. Global config: ~/.cursor/mcp.json — applies to every workspace. Project-scoped config: .cursor/mcp.json at the root of the repo — committed alongside the code. Cursor merges both, with project-scope taking precedence on name conflicts.

Do I have to restart Cursor after editing mcp.json?

Reload Window (Cmd/Ctrl+Shift+P) is enough in most cases. If a server seems stuck, fully quit and reopen. Cursor does not live-reload mcp.json — every edit needs at least a window reload.

Can my Claude Desktop config work in Cursor unchanged?

Almost — both use "mcpServers" as the top-level key with the same shape. Copy the block from claude_desktop_config.json into ~/.cursor/mcp.json and it works as-is. Cursor just adds the optional .cursor/mcp.json project-scoping path.

Why is my Python-based MCP server failing in Cursor?

Cursor invokes whatever you put in command. For Python servers use "command": "uvx" or "command": "python" instead of "npx", and pass the package or script as args. The MCP protocol itself is language-agnostic — only the launcher changes.

Next steps

One server is wired up. Now pick the rest of the stack — the six MCPs every Cursor user should install.

Best MCPs for CursorSecure your MCPs →