> ## 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.

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

Moving from Granola? Connect both servers to your assistant and use the [copyable meeting-note prompt](https://docs.screenpipe.com/meeting-intelligence.md#bring-your-granola-notes-with-you).

| 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 |
| Antigravity | Settings → Connections → AI apps | Restart or reconnect | Uses the current global MCP config |
| Cline in VS Code | Settings → Connections → AI apps | Refresh MCP servers | Default VS Code profile only |
| Kiro IDE | Settings → Connections → AI apps | Reconnect if needed | Workspace and agent configs can override the global entry |
| Perplexity on Mac | Settings → Connections → AI apps → Set up | Follow Perplexity's helper setup | Manual setup, status and removal in Perplexity |
| 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"`.

## Antigravity, Cline, Kiro, and Perplexity

Open each installed app once, then open **Settings → Connections → AI apps** in Screenpipe.

Antigravity, Cline in the default VS Code profile, and Kiro IDE support Connect and Remove. These integrations use MCP only, preserve other servers and settings, and remember removal so startup does not reconnect them. Their global config paths are:

* Antigravity: `~/.gemini/config/mcp_config.json` ([client documentation](https://antigravity.google/docs/mcp)).
* Cline: VS Code's user directory → `globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`. Other VS Code profiles, editor forks, and Cline CLI use separate configs; configure those through Cline's MCP settings ([client documentation](https://docs.cline.bot/mcp/mcp-overview)).
* Kiro IDE: `~/.kiro/settings/mcp.json` ([client documentation](https://kiro.dev/docs/mcp/configuration/)).

Project-level overrides and organization policies still apply. After connecting, restart or refresh the assistant, approve Screenpipe when prompted, and verify a real retrieval below.

For **Perplexity on Mac**, select **Set up**. Install Perplexity's helper from its Connectors settings, add a Simple connector named Screenpipe, and use **Copy setup command**. That command contains your local access key, so paste it only into the connector settings. Wait for Running and enable Screenpipe under Sources. Availability depends on your Perplexity plan. Screenpipe cannot verify or remove that manually managed connection; use Perplexity's Connectors settings. See [Perplexity's setup guide](https://www.perplexity.ai/help-center/en/articles/11502712-local-and-remote-mcps-for-perplexity).

Once retrieval works, try: “Use Screenpipe to summarize today by client and draft my timesheet. Cite the activity you found.”

## Verify a real retrieval

1. Keep Screenpipe running and verify `curl --fail-with-body http://localhost:3030/health`.
2. Display a harmless, distinctive phrase in a text editor for a few seconds. Note the time and confirm that moment appears in the timeline.
3. Open a new session in your connected assistant and ask it to search Screenpipe for that phrase in the last five minutes, returning the source app and timestamp.
4. Confirm that a Screenpipe tool actually ran and its result matches the timeline. An installed connection or a plausible answer is not proof of access.

If protected API requests return `401`, retrieve the local token with `npx -y screenpipe@latest auth token` and configure `SCREENPIPE_LOCAL_API_KEY` in the MCP process environment. Never paste the token into a conversation. An empty search with successful authentication needs a [capture and filter check](https://docs.screenpipe.com/missing-recordings.md).

An MCP connection to a documentation website searches documentation. It does not connect that assistant to your computer's recordings. Use the local Screenpipe MCP server described here for screen and audio history.

## 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.

### 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={"system"}
{
  "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={"system"}
claude mcp add screenpipe --transport stdio -- npx -y screenpipe-mcp
```

To make it available across all your projects:

```bash theme={"system"}
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.

### Manual setup (stdio)

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

```toml theme={"system"}
[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={"system"}
[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={"system"}
{
  "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.

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={"system"}
npx -y screenpipe-mcp
```

Add this as a stdio MCP server in your editor's MCP settings. See also:

* [Continue setup](https://docs.screenpipe.com/continue.md)
* [Cline setup](https://docs.screenpipe.com/cline.md)

## 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={"system"}
npx -y --package screenpipe-mcp screenpipe-mcp-http --port 3031
```

Set your HTTP MCP client URL to `http://127.0.0.1:3031/mcp`. Check server health with `curl --fail-with-body http://127.0.0.1:3031/health`. The binary is included in the `screenpipe-mcp` package; it is not a separate npm package.

### 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={"system"}
npx -y --package screenpipe-mcp screenpipe-mcp-http --port 3031 --listen-on-lan --api-key your-secret-key
```

In the remote MCP client, set the server URL to `http://<your-machine-ip>:3031/mcp` and configure the `Authorization: Bearer` header with the chosen key. `/mcp` is a protocol endpoint, not a REST search route; `/mcp/search` does not exist. Use a trusted private network and a transport appropriate for protecting the token and recording data.

The HTTP MCP access key and the recorder's local API token serve different connections. If MCP reaches the server but recording tools return `401`, check the recorder token in [Verify a real retrieval](#verify-a-real-retrieval).

> [!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.

## 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={"system"}
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](https://docs.screenpipe.com/api-recipes.md)
* [Privacy data flow](https://docs.screenpipe.com/privacy-data-flow.md)
* [Scheduled task debugging](https://docs.screenpipe.com/task-troubleshooting.md)

## Manual config (advanced)

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

**Manual JSON configuration**

**Cursor (project-scoped)** — create `.cursor/mcp.json` in your project root:

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

**From source:**

```bash theme={"system"}
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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.