Skip to content
justcrawl.io

Cursor

Add justcrawl as an MCP server in Cursor. Once wired, the chat / Composer can call jc_jobs_submit, jc_workflows_list, and the rest of the justcrawl tools directly — no copy-pasting curl into the terminal.

Prerequisites

Section titled “Prerequisites”
  • Cursor installed (download)
  • Node.js 20 or newer on PATH (node --version to check)
  • A justcrawl API key — Settings → API Keys in the dashboard. Starts with sr_live_.

Global vs per-project

Section titled “Global vs per-project”

Cursor reads MCP config from two files:

| Scope | Path | When to use | |-------|------|-------------| | Global | ~/.cursor/mcp.json | Every project gets justcrawl. Pick this if you work on scraping-adjacent code most days. | | Per-project | <repo>/.cursor/mcp.json | Only this repo gets justcrawl. Pick this if the team-shared repo should ship MCP config to teammates (commit the file). |

Per-project overrides global if both exist. You can put the API key in the per-project file and commit just the server name + command via a placeholder env (see "Sharing config with a team" below).

Configure

Section titled “Configure”

  1. Create the config file. If it doesn't exist:

    Terminal window
    # Global
    mkdir -p ~/.cursor && touch ~/.cursor/mcp.json
    

    # Per-project
    mkdir -p .cursor && touch .cursor/mcp.json

  2. Add the justcrawl block. Merge into the file (preserve any other servers):

    {
      "mcpServers": {
        "justcrawl": {
          "command": "npx",
          "args": ["-y", "@justcrawl/mcp-server"],
          "env": {
            "JUSTCRAWL_API_KEY": "sr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          }
        }
      }
    }

    Replace sr_live_xxxxx… with your real key.

  3. Reload Cursor. Either fully quit and reopen, or run the command palette command Developer: Reload Window (⌘⇧P → "Reload Window").

  4. Confirm it's wired. Open Cursor Settings → Features → MCP. You should see justcrawl listed with a green status. Hover the row to see the discovered tools.

First prompt to try

Section titled “First prompt to try”

In Composer or chat:

Use justcrawl to list my workflows.

Cursor calls jc_workflows_list() and shows the result inline. If you see the workflows from your dashboard, you're done.

Sharing config with a team

Section titled “Sharing config with a team”

To commit .cursor/mcp.json to a shared repo without leaking your API key:

{
  "mcpServers": {
    "justcrawl": {
      "command": "npx",
      "args": ["-y", "@justcrawl/mcp-server"],
      "env": {
        "JUSTCRAWL_API_KEY": "${JUSTCRAWL_API_KEY}"
      }
    }
  }
}

Each teammate sets JUSTCRAWL_API_KEY in their shell rc (or via Cursor's settings → Environment variables). Cursor expands ${VAR} at process spawn time.

Add .env, .env.local, etc. to .gitignore even with this pattern — defense in depth.

Troubleshooting

Section titled “Troubleshooting”

Server shows as missing or unconfigured in Settings → Features → MCP. Check the per-project vs global precedence — if a per-project .cursor/mcp.json exists, it overrides the global file for that workspace. To disable the server for a single project, delete (or rename) the justcrawl block in the per-project file. To disable it everywhere, do the same to the global one.

command not found: npx. Node.js isn't on the PATH Cursor sees. On macOS, install Node via the official installer (not nvm) so it lands in /usr/local/bin. Restart Cursor.

401 unauthorized in the stderr panel. The API key is malformed or revoked. Generate a fresh one in the dashboard and update mcp.json.

Stderr shows npm error 404 Not Found - GET https://registry.npmjs.org/@justcrawl%2Fmcp-server. The package isn't published yet (Phase 3). Your config is correct — reload the Cursor window after the package lands and the same config will spawn the real server.

Section titled “Related”