# Install Subio Scrape with your AI agent

No terminal knowledge required. There is **no account, no API key and no token** —
the server runs entirely on your machine.

## The short version

If your client has a CLI, one command is enough:

```bash
claude mcp add subio-scrape -- npx -y github:alijancb/subio-mcp
```

## Let your agent install it

1. Open the folder for your client below and download its `INSTALL.md`.
2. Attach that file to a new conversation with the client.
3. Say: **"Install Subio Scrape for me and verify it works."**

Each guide is written as instructions to the agent. It tells it to check your
Node version, find or install a browser, preserve every MCP server you already
have, and prove the install by actually calling a tool — not to stop at printing
commands.

| Your client | Guide |
| --- | --- |
| Claude Code, Claude Desktop | [`Claude/INSTALL.md`](Claude/INSTALL.md) |
| Codex | [`Codex/INSTALL.md`](Codex/INSTALL.md) |
| Cursor | [`Cursor/INSTALL.md`](Cursor/INSTALL.md) |
| Windsurf, Cline, Zed, VS Code, anything else that speaks MCP | [`Other-agents/INSTALL.md`](Other-agents/INSTALL.md) |

## What every install needs

- **Node.js 20 or newer** — `node --version`.
- **A browser.** Chrome or Edge is used if present; otherwise
  `npx playwright install chromium` once.
- **A desktop session.** The browser window must be able to appear on screen. X
  answers a headless browser with an empty 403, so this cannot run on a headless
  server or inside a container without a display.

## Two ways to install

**From GitHub, no clone** — simplest, and what the guides use:

```bash
npx -y github:alijancb/subio-mcp
```

The first start clones and builds, which takes a minute. Later starts are fast.

**From a local clone** — faster to start, and the only way to get the Claude Code
plugin with its `/scrape` command:

```bash
git clone https://github.com/alijancb/subio-mcp.git ~/subio-mcp && cd ~/subio-mcp && npm install
```

`npm install` builds the server, so `~/subio-mcp/dist/server.js` is ready to use
as the command in any client's config.

## Verifying an install

Ask your agent to call `browser_status`. A working install answers with something
like:

```json
{
  "open": false,
  "profile": "/Users/you/.subio-mcp/browser-profile",
  "channel": "chrome, then msedge, then bundled chromium",
  "headless": false,
  "signedIn": false,
  "windows": "one window, one tab, reused for the whole scan; closes itself when idle",
  "onBlock": "reading stops. Nothing here retries a refusal."
}
```

That call touches no website, so it is safe to run as a smoke test. For a real
check, ask for one post from one account — `x_account_posts` with
`handles: ["naval"]` and `limit: 1`. A browser window will open; that is expected
and required.

## If something goes wrong

| What you see | What it means |
| --- | --- |
| The agent lists no `subio-scrape` tools | The config was written but the client was not restarted. Restart it. |
| `Could not start a browser` | No Chrome or Edge, and no bundled Chromium. Run `npx playwright install chromium`. |
| `X answered 403 … with an empty page` | The browser ran headless. Unset `SUBIO_MCP_HEADLESS` and make sure a desktop session is available. |
| `LinkedIn put up its sign-in wall` | Normal. LinkedIn walls a signed-out client after a few pages. Wait, then read fewer. |
| `not-found: X sent @… to its signup page` | Usually a typo in the handle. X redirects handles that do not exist. |
| The first start hangs for a minute | `npx` is cloning and building. Only the first time. |