Skip to content
AgentAtlas

Cursor settings: settings.json, Cursor Settings and the ~/.cursor config files

How do I find and edit Cursor's settings files?

Cursor has two settings surfaces: the Cursor Settings panel (Ctrl/Cmd + Shift + J) for AI and agent features, and the VS Code style editor settings opened with Preferences: Open Settings (UI). Agent tooling is configured with JSON files in ~/.cursor for your user and in .cursor inside a project, such as mcp.json, permissions.json, hooks.json and cli-config.json. You can import your VS Code extensions, themes, settings and keybindings in one click.

Compare: settings file locations in every AI coding agent →

Open Cursor Settings and editor settings

  • Cursor Settings: press Ctrl/Cmd + Shift + J, or open the Command Palette (Ctrl/Cmd + Shift + P) and type "Cursor Settings".
  • Editor settings: open the Command Palette and run "Preferences: Open Settings (UI)".
  • Profiles: run "Preferences: Open Profiles (UI)" to manage, import or export profiles.

Cursor is built on the VS Code codebase, so editor keys such as editor.formatOnSave go in your user settings.json.

settings.json

{
  "security.workspace.trust.enabled": true,
  "editor.formatOnSave": true
}

Import your VS Code setup

  • Press Ctrl/Cmd + Shift + J to open Cursor Settings.
  • Go to General, then Account.
  • Under VS Code Import, click Import. This brings over extensions, themes, settings and keybindings.

For more control, export a profile in VS Code, then in Cursor run Preferences: Open Profiles (UI), choose Import Profile, paste a GitHub Gist URL or select the file, and activate the profile.

The activity bar is horizontal by default. Set workbench.activityBar.orientation to vertical and restart Cursor to change it.

MCP servers: mcp.json

  • Global: ~/.cursor/mcp.json, for tools available in every project.
  • Project: .cursor/mcp.json in the project root, for project specific tools.

~/.cursor/mcp.json

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

Agent auto-run rules: permissions.json

  • Global: ~/.cursor/permissions.json applies everywhere.
  • Project: <workspace>/.cursor/permissions.json applies to that workspace. Commit it to share rules with teammates.
  • When both exist, their arrays are combined. Cursor re-reads the files when they change and supports JSONC comments.
  • Keys include mcpAllowlist (server:tool entries) and terminalAllowlist (command prefixes).
  • A key in the file overrides the matching in-app allowlist. The docs call these allowlists best-effort, not a security boundary.

~/.cursor/permissions.json

{
  "terminalAllowlist": ["git", "npm", "pnpm", "make"],
  "mcpAllowlist": ["github:*"]
}

Cursor CLI: cli-config.json

  • macOS and Linux: ~/.cursor/cli-config.json
  • Windows: $env:USERPROFILE\.cursor\cli-config.json
  • Project: <project>/.cursor/cli.json (only permissions can be set at project level).
  • CURSOR_CONFIG_DIR sets a custom directory.

~/.cursor/cli-config.json

{
  "version": 1,
  "editor": { "vimMode": false },
  "permissions": {
    "allow": ["Shell(ls)", "Shell(echo)"],
    "deny": ["Shell(rm)"]
  }
}

Other files Cursor reads from ~/.cursor

  • ~/.cursor/hooks.json: user hooks (project version is .cursor/hooks.json).
  • ~/.cursor/sandbox.json: sandbox settings (project version is .cursor/sandbox.json).
  • ~/.cursor/skills/: user skills (project version is .cursor/skills/).
  • ~/.cursor/agents/: user subagents (project version is .cursor/agents/).

Sources

More Cursor guides

Reviewed Oct 18, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →