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.

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

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).
• 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).
• Kiro IDE: ~/.kiro/settings/mcp.json (client documentation).

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.

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.

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?”

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:

{
  "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:

claude mcp add screenpipe --transport stdio -- npx -y screenpipe-mcp

To make it available across all your projects:

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?”

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:

[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:

[mcp_servers.screenpipe.env]
SCREENPIPE_LOCAL_API_KEY = "your-local-api-key"

Cursor

Click here to install in cursor

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:

{
  "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?”

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:

npx -y screenpipe-mcp

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

• Continue setup
• Cline setup

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)

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:

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.

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:

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 — the community can help debug MCP issues.

Requirements

• Screenpipe must be running on localhost:3030
• Node.js >= 18.0.0

Deeper guides

• API recipes
• Privacy data flow
• Scheduled task 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:

Show Manual JSON configuration

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

{
  "mcpServers": {
    "screenpipe": {
      "command": "npx",
      "args": ["-y", "screenpipe-mcp"]
    }
  }
}

From source:

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.