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

# MCP server setup for Codex, Claude, Cursor, and AI tools

> Set up screenpipe as a Model Context Protocol server so Codex, Claude, and Cursor can search your screen history and audio transcripts.

{/* https://screenpi.pe */}

screenpipe provides an MCP (Model Context Protocol) server that lets AI assistants like Codex, Claude, and Cursor search your screen recordings, audio transcriptions, and control your computer.

## choose your MCP setup

| client                                | best path                                                                           | restart needed             | notes                                         |
| ------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------- | --------------------------------------------- |
| Claude Desktop                        | one-click install from settings -> connections                                      | yes                        | restart Claude completely after install       |
| Claude Code                           | `claude mcp add screenpipe --transport stdio --scope user -- npx -y screenpipe-mcp` | new session                | use `/mcp` to verify                          |
| Codex                                 | one-click connect from settings -> connections                                      | new session                | writes `~/.codex/config.toml`                 |
| Cursor                                | deep link or global MCP config                                                      | usually yes                | project configs can override global configs   |
| Warp                                  | paste per-server JSON in MCP settings                                               | no, but reconnect if stale | Warp does not use the Claude JSON wrapper     |
| Msty                                  | HTTP MCP server                                                                     | no                         | useful when the client expects HTTP transport |
| Cline, Continue, Gemini CLI, OpenCode | stdio MCP                                                                           | depends on client          | use `npx -y screenpipe-mcp`                   |

<Tip>
  the MCP server talks to the local screenpipe API. if MCP works but returns empty results, first check `curl http://localhost:3030/health` and `curl "http://localhost:3030/search?limit=1"`.
</Tip>

## claude desktop

### quick setup (recommended)

open the **screenpipe app** → **settings** → **connections** → click **"install extension"**

Claude will open and prompt you to confirm. click **install** — done!

try asking Claude: *"what did I do in the last 5 minutes?"*

<Tip>
  make sure screenpipe is running when you use Claude with screenpipe features.
</Tip>

### manual setup (stdio)

if the one-click install doesn't appear or you prefer manual config, edit Claude's config file directly:

**macOS:** `~/Library/Application\ Support/Claude/claude_desktop_config.json`

**Windows:** `%AppData%\Claude\claude_desktop_config.json`

add or update the `mcpServers` section:

```json theme={null}
{
  "mcpServers": {
    "screenpipe": {
      "command": "npx",
      "args": ["-y", "screenpipe-mcp"],
      "transport": "stdio"
    }
  }
}
```

save, then **restart Claude Desktop completely** (force-quit from Activity Monitor / Task Manager, then reopen). verify the connection works by asking Claude: *"what's on my screen right now?"*

## claude code

one command:

```bash theme={null}
claude mcp add screenpipe --transport stdio -- npx -y screenpipe-mcp
```

to make it available across all your projects:

```bash theme={null}
claude mcp add screenpipe --transport stdio --scope user -- npx -y screenpipe-mcp
```

verify with `claude mcp list` or `/mcp` inside Claude Code.

## codex

### quick setup (recommended)

open the **screenpipe app** → **settings** → **connections** → click **connect** next to Codex.

screenpipe writes the MCP server to `~/.codex/config.toml`. open a new Codex session, then try: *"what did I do in the last 5 minutes?"*

<Tip>
  make sure screenpipe is running when you use Codex with screenpipe features.
</Tip>

### manual setup (stdio)

if the one-click install doesn't appear or you prefer manual config, edit `~/.codex/config.toml` and add:

```toml theme={null}
[mcp_servers.screenpipe]
command = "npx"
args = ["-y", "screenpipe-mcp"]
enabled = true
```

save, then open a new Codex session. if you use a local screenpipe API key, set it in the same block:

```toml theme={null}
[mcp_servers.screenpipe.env]
SCREENPIPE_LOCAL_API_KEY = "your-local-api-key"
```

## cursor

[click here to install in cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=screenpipe\&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNjcmVlbnBpcGUtbWNwIl19)

or manually: open **cursor settings** → **mcp** → **add new global mcp server** → set command to `npx` with args `["-y", "screenpipe-mcp"]`.

## warp

Warp's Agent Mode supports MCP. Open **Settings** → **AI** → **Manage MCP servers** → **+ Add**, choose **CLI Server (Command)**, then paste:

```json theme={null}
{
  "screenpipe": {
    "command": "npx",
    "args": ["-y", "screenpipe-mcp"],
    "start_on_launch": true
  }
}
```

Save — the server should show **Running**. Then ask Warp's agent: *"what did I do in the last 5 minutes?"*

<Tip>
  Warp's MCP schema is per-server (no wrapping `mcpServers` object). Don't paste the Claude/Cursor JSON shape — it won't validate.
</Tip>

You can also reach this screen via the Command Palette → *Open MCP Servers*. Or just open the screenpipe app → **settings** → **connections** → **Warp** to copy the config.

## other editors (cline, continue, windsurf, etc.)

any editor that supports MCP works with screenpipe. the server command is:

```bash theme={null}
npx -y screenpipe-mcp
```

add this as a stdio MCP server in your editor's MCP settings. see also:

* [continue setup](/continue)
* [cline setup](/cline)

## HTTP transport (optional)

if you need remote MCP access or prefer HTTP over stdio, the `screenpipe-mcp` npm package includes an HTTP server binary. both the stdio (`screenpipe-mcp`) and HTTP (`screenpipe-mcp-http`) commands come from the same npm package.

### localhost only (default)

```bash theme={null}
npx -y screenpipe-mcp-http --port 3031
```

this starts an HTTP MCP server on `http://127.0.0.1:3031`. useful for tools like [Msty](https://msty.studio) that support HTTP MCP transport.

### expose to your LAN

to access the server from other machines on your network, use `--listen-on-lan`. **this requires an API key for security:**

```bash theme={null}
npx -y screenpipe-mcp-http --port 3031 --listen-on-lan --api-key your-secret-key
```

then from a remote machine, call the server with the bearer token:

```bash theme={null}
curl -H "Authorization: Bearer your-secret-key" \
  http://<your-machine-ip>:3031/mcp/search?q=example
```

<Warning>
  HTTP MCP can expose screen history. when using `--listen-on-lan`, always set an `--api-key` — screenpipe will refuse to start without it. keep the key secret and only share with trusted services.
</Warning>

## available tools

### search-content (all platforms)

search through recorded screen content, audio transcriptions, and user input events:

| parameter        | type    | description                                                         |
| ---------------- | ------- | ------------------------------------------------------------------- |
| `q`              | string  | search query (optional - omit to get recent content)                |
| `content_type`   | string  | `all`, `ocr`, `audio`, `input`, or `accessibility` (default: `all`) |
| `limit`          | integer | max results (default: 10)                                           |
| `offset`         | integer | pagination offset (default: 0)                                      |
| `start_time`     | string  | ISO 8601 UTC start time (e.g., `2024-01-15T10:00:00Z`)              |
| `end_time`       | string  | ISO 8601 UTC end time                                               |
| `app_name`       | string  | filter by app (e.g., `Google Chrome`, `Slack`)                      |
| `window_name`    | string  | filter by window title                                              |
| `min_length`     | integer | minimum content length                                              |
| `max_length`     | integer | maximum content length                                              |
| `include_frames` | boolean | include base64 screenshots for screen-text results                  |
| `speaker_ids`    | string  | comma-separated speaker IDs for audio filtering (e.g., `1,2,3`)     |
| `speaker_name`   | string  | filter audio by speaker name (case-insensitive partial match)       |

### export-video

create video exports from screen recordings for a specific time range:

| parameter    | type   | description                        |
| ------------ | ------ | ---------------------------------- |
| `start_time` | string | ISO 8601 UTC start time (required) |
| `end_time`   | string | ISO 8601 UTC end time (required)   |
| `fps`        | number | frames per second (default: 1.0)   |

## example queries

try these in Claude or Cursor:

* "search for any mentions of 'project' in my screen recordings"
* "find audio transcriptions from the last hour"
* "show me what was on my screen in VS Code yesterday"
* "export a video of my screen from 10am to 11am today"
* "find what John said in our meeting about the API"
* "what did I type in Slack today?" (uses content\_type=input)
* "what did I copy to my clipboard recently?" (uses content\_type=input)

## testing

test your setup with MCP Inspector:

```bash theme={null}
npx @modelcontextprotocol/inspector npx screenpipe-mcp
```

## troubleshooting

| symptom                                     | likely fix                                                                                                                 |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| no MCP tools appear                         | restart the client and verify the config path                                                                              |
| mcp not connecting                          | ensure screenpipe is running and reachable at `http://localhost:3030/health`, then restart the client after config changes |
| `npx` not found                             | install Node.js 18+ or use the one-click in-app setup                                                                      |
| `403` or unauthorized                       | set `SCREENPIPE_LOCAL_API_KEY` or refresh API auth in settings                                                             |
| empty results                               | wait for capture, broaden the query, or verify `/search?limit=1`                                                           |
| client hangs on startup                     | run the inspector command above and check Node version                                                                     |
| Claude Desktop on Windows cannot see config | check whether you use the normal or Microsoft Store/MSIX install                                                           |
| Codex does not see screenpipe               | open a new Codex session after the app writes `~/.codex/config.toml`                                                       |
| HTTP transport not reachable                | confirm `screenpipe-mcp-http` port and firewall/LAN rules                                                                  |
| macOS automation not working                | grant accessibility permissions in System Settings → Privacy & Security → Accessibility                                    |

still stuck? [ask in our discord](https://discord.gg/screenpipe) — the community can help debug MCP issues.

## requirements

* screenpipe must be running on localhost:3030
* Node.js >= 18.0.0

## deeper guides

* [API recipes](/api-recipes)
* [privacy data flow](/privacy-data-flow)
* [pipe debugging](/pipe-debugging)

## manual config (advanced)

the per-client manual setups above (Claude Desktop, Codex) cover most cases. these extra targets are for editors not listed above:

<Expandable title="manual JSON configuration">
  **cursor (project-scoped)** — create `.cursor/mcp.json` in your project root:

  ```json theme={null}
  {
    "mcpServers": {
      "screenpipe": {
        "command": "npx",
        "args": ["-y", "screenpipe-mcp"]
      }
    }
  }
  ```

  **from source:**

  ```bash theme={null}
  git clone https://github.com/screenpipe/screenpipe
  cd screenpipe/packages/screenpipe-mcp
  npm install && npm run build
  ```

  then point your editor to `node /path/to/screenpipe-mcp/dist/index.js`.
</Expandable>