> ## 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](/meeting-intelligence#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 |
| 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={"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.
</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={"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.
</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={"system"}
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={"system"}
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={"system"}
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={"system"}
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={"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](/api-recipes)
* [Privacy data flow](/privacy-data-flow)
* [Scheduled task debugging](/task-troubleshooting)

## 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={"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`.
</Expandable>


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