Skip to main content
screenpipe provides an MCP (Model Context Protocol) server that lets AI assistants like Claude and Cursor search your screen recordings, audio transcriptions, and control your computer.

​
what is MCP?

MCP (Model Context Protocol) is an open standard that allows AI assistants to connect to external data sources and tools. screenpipe implements MCP to expose your screen and audio history to compatible AI applications. 
┌─────────────────────────────────────────────┐
│  AI Assistant (Claude, Cursor, etc.)        │
│             ↕ MCP Protocol                  │
│  screenpipe MCP Server (localhost:3030)     │
│             ↕ REST API                      │
│  screenpipe Core (recording + storage)      │
└─────────────────────────────────────────────┘

​
quick setup

the fastest way to get started:
1

Install screenpipe MCP

npx -y screenpipe-mcp
this downloads and runs the latest MCP server automatically.
2

Add to your AI assistant

see the specific setup guides below for your application:
3

Start using it

ask your AI assistant: “what did I do in the last 5 minutes?”
make sure screenpipe is running when you use MCP features.

​
transport modes

screenpipe MCP supports two transport modes:

​
stdio (standard input/output)

for local AI assistants running on the same machine: 
npx -y screenpipe-mcp
use cases:
  • Claude Desktop
  • Cursor
  • VS Code extensions (Cline, Continue)
  • local MCP clients

​
HTTP (network transport)

for remote AI assistants or network access: 
npx screenpipe-mcp-http --port 3031
use cases:
  • AI assistants on different machines
  • OpenClaw running on VPS
  • team deployments
  • network testing

​
available tools

when connected via MCP, AI assistants get access to these tools:

​
search-content

search through recorded content with filtering:
parametertypedescription
qstringsearch query (optional - omit to get recent content)
content_typestringall, ocr, audio, input, or accessibility (default: all)
limitintegermax results (default: 10)
offsetintegerpagination offset (default: 0)
start_timestringISO 8601 UTC start time (e.g., 2024-01-15T10:00:00Z)
end_timestringISO 8601 UTC end time
app_namestringfilter by app (e.g., Google Chrome, Slack)
window_namestringfilter by window title
min_lengthintegerminimum content length
max_lengthintegermaximum content length
include_framesbooleaninclude base64 screenshots (OCR only)
speaker_idsstringcomma-separated speaker IDs for audio filtering (e.g., 1,2,3)
speaker_namestringfilter audio by speaker name (case-insensitive partial match)
content types:
  • all - everything (OCR + audio + accessibility + input)
  • ocr - screen text from screenshots (legacy)
  • audio - audio transcriptions from meetings/calls
  • input - user actions (clicks, keystrokes, clipboard, app switches)
  • accessibility - accessibility tree text (preferred for screen content)

​
export-video

create video exports from screen recordings:
parametertypedescription
start_timestringISO 8601 UTC start time (required)
end_timestringISO 8601 UTC end time (required)
fpsnumberframes per second (default: 1.0)

​
activity-summary

get lightweight activity overview for a time range:
  • app usage with active minutes and frame counts
  • recent accessibility texts
  • audio speaker summary

​
list-meetings

list detected meetings with duration, app, and attendees (requires smart transcription mode).

​
search-elements

search structured UI elements (accessibility tree nodes and OCR text blocks) - lighter than search-content for targeted lookups.

​
frame-context

get accessibility text, parsed tree nodes, and extracted URLs for a specific frame.

​
example queries

try these in any MCP-compatible AI assistant: 
> 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)

> show me my app usage for the last 2 hours

​
testing your setup

use MCP Inspector to test your configuration: 
npx @modelcontextprotocol/inspector npx screenpipe-mcp
this opens a web interface at http://localhost:5173 where you can:
  • test all available tools
  • view tool schemas
  • send test queries
  • debug responses

​
manual configuration

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "screenpipe": {
      "command": "npx",
      "args": ["-y", "screenpipe-mcp"]
    }
  }
}

​
building from source

for development or custom builds: 
git clone https://github.com/screenpipe/screenpipe
cd screenpipe/crates/screenpipe-connect/screenpipe-mcp
bun install
bun run build
then point your MCP client to the built file: 
{
  "mcpServers": {
    "screenpipe": {
      "command": "node",
      "args": ["/absolute/path/to/screenpipe-mcp/dist/index.js"]
    }
  }
}

​
troubleshooting

MCP not connecting?
  • ensure screenpipe is running: curl http://localhost:3030/health
  • restart your AI assistant after config changes
  • check logs in the AI assistant’s developer console
no data returned?
  • verify screenpipe has data: curl "http://localhost:3030/search?limit=1"
  • ensure screen recording permissions are granted
  • check the time range you’re querying
macOS automation not working?
  • grant accessibility permissions in System Settings > Privacy & Security > Accessibility
  • ensure screenpipe app is listed and enabled
queries timing out?
  • reduce limit parameter
  • narrow the time range
  • avoid using include_frames unless needed (large responses)
still stuck? ask in our discord — the community can help debug MCP issues.

​
resources

Build docs developers (and LLMs) love

Get started for freeTalk to us