Skip to main content
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=ocr"
```
Restart OpenClaw to load the skill.

​
different machines

If OpenClaw runs on a remote server (e.g., a VPS) and screenpipe runs on your laptop/desktop, you need to expose screenpipe to the remote machine. There are two approaches: MCP over HTTP (recommended) and REST API with custom skills (fallback). Screenpipe’s MCP server supports Streamable HTTP transport, so OpenClaw can connect to it as a proper MCP server over the network — all tools, fully described, structured calls. No curl workarounds needed. Step 1: On your computer (where screenpipe runs), start the HTTP MCP server: 
npx screenpipe-mcp-http --port 3031
This starts the MCP server on http://localhost:3031/mcp. Step 2: Expose port 3031 to your OpenClaw server using one of:
Tailscale creates a private network between your devices — no port forwarding, no config files.
  1. Install Tailscale on both machines
  2. Run tailscale up on both
  3. Find your computer’s Tailscale IP: tailscale ip
  4. Verify: curl http://<tailscale-ip>:3031/health
Your MCP URL will be http://<tailscale-ip>:3031/mcp.
Forward the MCP port over SSH:
# on your computer (where screenpipe runs)
ssh -R 3031:localhost:3031 user@openclaw-server

# or persistent with autossh
autossh -M 0 -f -N -R 3031:localhost:3031 user@openclaw-server
Your MCP URL will be http://localhost:3031/mcp (on the OpenClaw server).
# on your computer
cloudflared tunnel --url http://localhost:3031
Your MCP URL will be the https:// URL cloudflared gives you, with /mcp appended.
Step 3: Configure OpenClaw to use the remote MCP server: 
{
  "mcpServers": {
    "screenpipe": {
      "url": "http://<your-mcp-url>:3031/mcp"
    }
  }
}
Replace <your-mcp-url> with the appropriate address from step 2 (Tailscale IP, localhost for SSH tunnel, or Cloudflare URL). Restart OpenClaw — it now has full MCP access to screenpipe with all tools, parameters, and structured responses. No custom skills needed.
The HTTP MCP transport means OpenClaw gets the same experience remotely as it does locally — tool discovery, typed parameters, structured results. This is the same approach Pieces uses to expose MCP over the network.

​
REST API with custom skills (fallback)

If OpenClaw doesn’t support HTTP MCP transport, you can fall back to custom skills that call screenpipe’s REST API directly. This works but is less structured — OpenClaw won’t get MCP tool discovery or typed parameters.

​
option A: Tailscale + REST

  1. Install Tailscale on both machines, run tailscale up on both
  2. Find your Tailscale IP: tailscale ip
  3. Verify: curl http://<tailscale-ip>:3030/health
  4. 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://TAILSCALE_IP:3030.

## search content

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

## filter by type

```bash
# screen content (accessibility + OCR)
curl -s "http://TAILSCALE_IP:3030/search?q=QUERY&content_type=all"

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

# user input (keyboard, clicks, clipboard)
curl -s "http://TAILSCALE_IP:3030/search?q=QUERY&content_type=input"
```

## filter by app

```bash
curl -s "http://TAILSCALE_IP:3030/search?q=QUERY&app_name=Chrome"
```

## filter by time

```bash
curl -s "http://TAILSCALE_IP:3030/search?q=QUERY&start_time=2024-01-15T10:00:00Z&end_time=2024-01-15T18:00:00Z"
```

## activity summary (lightweight overview)

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

## list meetings

```bash
curl -s "http://TAILSCALE_IP:3030/meetings?limit=20"
```

## search UI elements

```bash
curl -s "http://TAILSCALE_IP:3030/elements?q=QUERY&limit=50"
```
Replace TAILSCALE_IP with your actual Tailscale IP (e.g., 100.64.x.x).

​
option B: SSH tunnel + REST

# on your computer (where screenpipe runs)
ssh -R 3030:localhost:3030 user@openclaw-server

# or persistent
autossh -M 0 -f -N -R 3030:localhost:3030 user@openclaw-server
This makes screenpipe available at localhost:3030 on your OpenClaw server. Then use the same skill as the “same machine” custom skill setup, replacing the URL accordingly.

​
option C: Cloudflare Tunnel + REST

# on your computer
cloudflared tunnel --url http://localhost:3030
Then point your OpenClaw skill at the tunnel URL.

​
available MCP tools

When connected via MCP (stdio or HTTP), OpenClaw gets access to these tools:
ToolDescription
search-contentSearch screen text (accessibility/OCR), 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