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

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:

• 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 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

• API recipes
• privacy data flow
• 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:

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.