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

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`

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

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:

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 screenpipe-mcp-http --port 3031

this starts an HTTP MCP server on http://127.0.0.1:3031. useful for tools like Msty 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:

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:

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

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

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.

get started

pipes

connect

use cases

integrations

reference

deployment

compare

resources

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

choose your MCP setup

claude desktop

quick setup (recommended)

manual setup (stdio)

claude code

codex

quick setup (recommended)

manual setup (stdio)

cursor

warp

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

HTTP transport (optional)

localhost only (default)

expose to your LAN

available tools

search-content (all platforms)

export-video

example queries

testing

troubleshooting

requirements

deeper guides

manual config (advanced)

​choose your MCP setup

​claude desktop

​quick setup (recommended)

​manual setup (stdio)

​claude code

​codex

​quick setup (recommended)

​manual setup (stdio)

​cursor

​warp

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

​HTTP transport (optional)

​localhost only (default)

​expose to your LAN

​available tools

​search-content (all platforms)

​export-video

​example queries

​testing

​troubleshooting

​requirements

​deeper guides

​manual config (advanced)

choose your MCP setup

claude desktop

quick setup (recommended)

manual setup (stdio)

claude code

codex

quick setup (recommended)

manual setup (stdio)

cursor

warp

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

HTTP transport (optional)

localhost only (default)

expose to your LAN

available tools

search-content (all platforms)

export-video

example queries

testing

troubleshooting

requirements

deeper guides

manual config (advanced)