> ## Documentation Index
> Fetch the complete documentation index at: https://help.lobstr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect lobstr.io to Cursor and run scrapers from the editor

> Add the lobstr.io MCP server to Cursor so Agent can find a scraper, launch a run, and pull the results straight into your project.

Cursor can operate your lobstr.io account directly through the lobstr.io **MCP server**. You ask Agent for the data you need, and it picks the right scraper, launches the run in your account, and brings the results back into the chat or into a file in your project.

**Endpoint:** `https://mcp.lobstr.io/mcp`

<Note>
  This is the **operational** server. It acts in your account and spends credits. A separate public server at `https://docs.lobstr.io/mcp` only answers questions about the lobstr.io API and can't touch your account. You can add both, see [Add the docs server too](#add-the-docs-server-too).
</Note>

## Before you start

* A [lobstr.io account](https://app.lobstr.io) with credits. Launching a run spends credits from your balance.
* The Cursor desktop app.

You don't need your API key. The connection uses OAuth: you approve it on lobstr.io's own site, so **no password ever reaches Cursor**.

## Connect Cursor to lobstr.io

<Steps>
  <Step title="Open your MCP config">
    Cursor reads MCP servers from a JSON file. Pick where the server should be available:

    * `~/.cursor/mcp.json` for every project on your machine
    * `.cursor/mcp.json` in a project's root for that project only

    Create the file if it doesn't exist.
  </Step>

  <Step title="Add the lobstr.io server">
    Paste this in, or add the `lobstr` entry to the `mcpServers` you already have:

    ```json theme={null}
    {
      "mcpServers": {
        "lobstr": {
          "url": "https://mcp.lobstr.io/mcp"
        }
      }
    }
    ```

    <Warning>
      Include the trailing `/mcp`. A URL without it won't connect.
    </Warning>

    No client ID or secret is needed. Cursor registers itself with lobstr.io automatically.
  </Step>

  <Step title="Approve the connection">
    Cursor opens the lobstr.io consent page in your browser. You're already signed in, so review the permissions and click **Allow**, then go back to Cursor.

    If the browser doesn't open, open **Customize** in Cursor's sidebar, find `lobstr` in your MCP servers, and start the sign-in from there.
  </Step>

  <Step title="Check it works">
    In Agent chat, ask *"Who am I on lobstr.io?"*. Agent replies with the account you're signed in as and your plan.
  </Step>
</Steps>

## Tool approval

By default Cursor asks before it uses any MCP tool. Click the arrow next to the tool name to see exactly what it's about to send, such as the scraper and the inputs for a run.

Cursor applies the same run modes to MCP tools as to terminal commands, so you can let read-only tools like `search_scrapers`, `get_run`, and `get_results` run without asking. Keep `run_scraper` on approval if you want to see every launch.

## What you're approving

The consent page lists the permissions Cursor is asking for, and you choose which ones to allow. You can revoke access at any time from your lobstr.io account.

| Permission | What it grants |
| - | - |
| `crawlers:read` | Discover scrapers and read their settings |
| `runs:read` | Check the status of your runs |
| `results:read` | Read your scraped results |
| `profile:read` | View your profile (name, email, plan) and credit balance |
| `account:read` | View your synced platform accounts (LinkedIn, Facebook, etc.) and their status |
| `runs:execute` | Run scrapers on your behalf (spends credits). Together with `account:read`, it also lets Cursor attach a synced account to a Squid |

## What Cursor can do

| Capability | Spends credits |
| - | - |
| Search the store for the right scraper | No |
| Read a scraper's inputs, output fields, and pricing | No |
| List and inspect your saved Squids | No |
| Create a Squid, add tasks, and change its settings without running it | No |
| Estimate a run's credits, result count, and duration | No |
| Launch a run | **Yes** |
| Check a run's status, wait for it to finish, or list a Squid's recent runs | No |
| Abort a run (results collected so far are kept) | No |
| Read a page of results, or get a download link (CSV, Excel, JSON, or JSONL) | No |
| Empty a Squid's tasks, or deactivate it to free its slots | No |
| Check your credit balance, slots, and plan | No |
| List your synced accounts and attach one to a Squid | No |

New scrapers work automatically. Cursor reads each scraper's live input schema, so nothing needs updating when lobstr.io adds one to the store.

## Scrapers that need a synced account

Some scrapers log in to a platform on your behalf, such as the LinkedIn and Sales Navigator scrapers. They need a synced account first, set up with [Account sync](/getting-started/account-sync).

* **One matching account:** if exactly one healthy synced account of the right type exists, Cursor attaches it for you.
* **Several or none:** Cursor asks you which account to use, or tells you which platform to sync.
* **The type must match.** A LinkedIn account can't run a Sales Navigator scraper, and the reverse.
* **Attaching only adds.** An account already on a Squid is never swapped out.

## A typical conversation

Because Agent works inside your project, it can put the data where your code expects it.

<Steps>
  <Step title="Find a scraper">
    *"Find a lobstr.io scraper for Google Maps business leads."*
  </Step>

  <Step title="Check what it needs">
    *"What inputs does it take, and what does it cost?"*
  </Step>

  <Step title="Launch the run">
    *"Run it for dentists in Manchester."* Cursor asks you to approve the tool call, and lobstr.io asks you to confirm the cost when the estimate is high.
  </Step>

  <Step title="Follow the run">
    *"Is it finished?"*
  </Step>

  <Step title="Put the data to work">
    *"Download the results as CSV into `data/dentists.csv`, then write a script that removes rows without a phone number."*
  </Step>
</Steps>

## Add the docs server too

If you're writing code against the lobstr.io API, add the public docs server next to the operational one. Agent can then look up endpoints and parameters while it writes your integration. It needs no sign-in.

```json theme={null}
{
  "mcpServers": {
    "lobstr": {
      "url": "https://mcp.lobstr.io/mcp"
    },
    "lobstr-docs": {
      "url": "https://docs.lobstr.io/mcp"
    }
  }
}
```

## Credits and confirmation

lobstr.io prices **per result row**, so the final cost of a run isn't known until it finishes. Before launching, Cursor estimates the cost, and when the estimate is high or can't be calculated, it asks you to confirm first. Reading scrapers, runs, and results never spends credits.

For a closer figure before anything launches, ask Cursor to estimate the run once the Squid has its tasks. If email verification is on, it's billed separately after the scrape.

<Warning>
  Runs launched from Cursor are real runs in your account. They appear in your dashboard with an `mcp` badge next to the Squid name, count against your [slots](/core-concepts/slots), and draw down the same credit balance as runs you launch yourself.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The connection fails or Cursor can't authorize">
    Check the URL is exactly `https://mcp.lobstr.io/mcp`, over HTTPS and with the `/mcp` path included. For details, open the Output panel (`Cmd+Shift+U` on Mac, `Ctrl+Shift+U` on Windows) and pick **MCP Logs** from the dropdown.
  </Accordion>

  <Accordion title="Agent doesn't use the lobstr.io tools">
    Open **Customize** in the sidebar and check the `lobstr` server is switched on. Disabled servers don't appear in chat. You can also name the tool you want, for example *"use search\_scrapers to find…"*.
  </Accordion>

  <Accordion title="Every run asks me to confirm">
    That's expected. lobstr.io charges per row, so the total is unknowable up front. The estimate still shows you the per-row rate.
  </Accordion>

  <Accordion title="A run stays pending or errors out">
    Open the run in your [lobstr.io dashboard](https://app.lobstr.io). Cursor sees the same status your account does, so the dashboard will show the same [stop reason](/core-concepts/run-stop-reasons).
  </Accordion>

  <Accordion title="Cursor says I'm over my slot limit">
    Your plan caps the total [slots](/core-concepts/slots) your active Squids can reserve. The cap is checked when a Squid is created, activated, or has its slots raised, not when a run starts. If creating a Squid fails because you're at the limit, deactivate Squids you don't need from the [dashboard](https://app.lobstr.io), or ask Cursor to do it. After a plan change the count can read above your limit; Squids that already exist keep running.
  </Accordion>

  <Accordion title="Only 30 results come back">
    On the free plan, reading results through the MCP server is capped at the first 30 rows. Upgrading your plan is the only way past it. See [Manage subscription](/billing/manage-subscription).
  </Accordion>
</AccordionGroup>