Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.screenpi.pe/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw is a self-hosted personal AI assistant that connects to your messaging apps (WhatsApp, Telegram, Discord, iMessage, etc.) and can take actions on your behalf. With screenpipe, OpenClaw can recall what you’ve seen on screen, reference past conversations, and answer questions about your digital history.

​
same machine

If OpenClaw and screenpipe run on the same machine, setup is straightforward. Add screenpipe to your OpenClaw MCP config: 
{
  "mcpServers": {
    "screenpipe": {
      "command": "npx",
      "args": ["-y", "screenpipe-mcp"]
    }
  }
}
Restart OpenClaw — it will now have access to your screen history, audio transcriptions, and more. You can test the MCP server independently: 
npx @modelcontextprotocol/inspector npx screenpipe-mcp

​
custom skill (alternative)

Create ~/openclaw/skills/screenpipe/skill.md: 
---
name: screenpipe
description: Search screen recordings and audio transcriptions from the user's computer
tools:
  - Bash
---

# screenpipe skill

Query the user's screen history via the local API at http://localhost:3030.

## search content

```bash
curl -s "http://localhost:3030/search?q=QUERY&limit=20"
```

## get recent activity

```bash
curl -s "http://localhost:3030/search?limit=10&content_type=all"
```
Restart OpenClaw to load the skill.

​
different machines

If OpenClaw runs on a different machine (e.g., a VPS or home server) than screenpipe, there are two ways to connect them:

​
option 1: query screenpipe’s REST API directly

If both machines are on the same network, OpenClaw can query screenpipe’s API directly. Use a custom skill: Create ~/openclaw/skills/screenpipe/skill.md: 
---
name: screenpipe
description: Search screen recordings and audio transcriptions from the user's computer
tools:
  - Bash
---

# screenpipe skill

Query the user's screen history via their screenpipe REST API at http://SCREENPIPE_IP:3030.

## search content

```bash
curl -s "http://SCREENPIPE_IP:3030/search?q=QUERY&limit=20"
```

## filter by type

```bash
# screen content (accessibility-first text plus OCR fallback)
curl -s "http://SCREENPIPE_IP:3030/search?q=QUERY&content_type=all"

# audio transcriptions
curl -s "http://SCREENPIPE_IP:3030/search?q=QUERY&content_type=audio"
```

## activity summary

```bash
curl -s "http://SCREENPIPE_IP:3030/activity-summary?start_time=2024-01-15T10:00:00Z&end_time=2024-01-15T18:00:00Z"
```

## list meetings

```bash
curl -s "http://SCREENPIPE_IP:3030/meetings?limit=20"
```
Replace SCREENPIPE_IP with the IP of the machine running screenpipe. If the machines aren’t on the same network, use Tailscale to create a private network between them.

​
option 2: push data to the OpenClaw machine over SSH

Use screenpipe’s built-in remote sync to push your ~/.screenpipe/ directory to the OpenClaw machine over SFTP. No screenpipe-cloud account needed — just SSH access to your server.
⚠️ clipboard sensitivity: Remote sync includes clipboard events and content by default. If you’re syncing to a less-trusted machine (VPS, shared server), disable clipboard capture first with --disable-clipboard-capture to avoid syncing passwords, API keys, or other sensitive data that flows through your clipboard.
On the laptop (or any machine recording): 
# one-shot push (excludes clipboard)
screenpipe sync remote now \
  --host openclaw.example.com \
  --user ubuntu \
  --key-path ~/.ssh/id_ed25519 \
  --remote-path /home/ubuntu/.screenpipe \
  --disable-clipboard-capture

# verify SSH first if you want
screenpipe sync remote test --host ... --user ... --key-path ... --remote-path ...

# auto-discover candidate hosts from ~/.ssh/config
screenpipe sync remote discover
Run that on a cron / launchd / systemd timer for continuous sync: 
# crontab -e — every 15 minutes (without clipboard)
*/15 * * * * /usr/local/bin/screenpipe sync remote now \
  --host openclaw.example.com --user ubuntu \
  --key-path /home/me/.ssh/id_ed25519 --remote-path /home/ubuntu/.screenpipe \
  --disable-clipboard-capture
Or set env vars instead of flags: SCREENPIPE_REMOTE_HOST, SCREENPIPE_REMOTE_USER, SCREENPIPE_REMOTE_KEY, SCREENPIPE_REMOTE_PATH. On the OpenClaw machine, point its skill at the synced directory or run a local screenpipe pointing to the same data dir — OpenClaw can then query localhost:3030 as if the data were captured locally.
The deprecated cloud sync flow (Settings → Cloud, screenpipe-cloud account) is being phased out in favor of self-hosted remote sync. Use screenpipe sync remote for new setups.

​
available MCP tools

When connected via MCP (same machine setup), OpenClaw gets access to these tools:
ToolDescription
search-contentSearch screen text (accessibility-first with OCR fallback), audio transcriptions, user input. Supports time range, app, window, and speaker filters.
activity-summaryLightweight overview of app usage, audio speakers, and recent texts for a time range (~200 tokens).
search-elementsSearch structured UI elements (buttons, links, text fields) from the accessibility tree.
frame-contextGet full accessibility tree, URLs, and text for a specific frame.
list-meetingsList detected meetings with duration, app, and attendees.
export-videoExport screen recordings as MP4 for a time range.
The MCP server also provides resources (screenpipe://context for current time, screenpipe://guide for search strategy) and prompts (search-recent, find-in-app, meeting-notes).

​
example prompts

Once configured, message OpenClaw from any chat app:
  • “what was I reading about yesterday afternoon?”
  • “find the slack message from john about the deployment”
  • “what code was I looking at in cursor this morning?”
  • “summarize my meetings from last week”
  • “what tabs did I have open when researching that bug?”
  • “when did I last see the budget spreadsheet?”
  • “what did I copy to clipboard recently?”
  • “show me what buttons I clicked in Figma today”

​
troubleshooting

MCP not connecting?
  • Test the server: npx @modelcontextprotocol/inspector npx screenpipe-mcp
  • Check screenpipe is running: curl http://localhost:3030/health
remote machine can’t reach screenpipe?
  • Check Tailscale is connected: tailscale status
  • Check SSH tunnel is up: curl http://localhost:3030/health on the remote
  • Make sure screenpipe is running on your computer
no results from queries?
  • Verify screenpipe is running: curl http://localhost:3030/health
  • Ensure screenpipe has screen recording permissions