# screenpipe [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/screenpipe/screenpipe  
**GitHub Stars:** 21725  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/screenpipe

## Description
Local-first workflow memory for AI agents. screenpipe lets MCP clients search selected screen, audio, app, and meeting context and turn real work into cited notes, SOPs, workflow reports, and automation candidates.

## Tools
Capabilities this server exposes over MCP:

- **search-content** — Search screen text, audio transcriptions, input events, memories, and parsed app data. Returns timestamped results with app context. USE WHEN: you need the actual text/content of a moment — quotes, screen text, transcript lines, or compact parsed messages, emails, tasks, documents, and code review — or want to filter by speaker/window. DO NOT USE for: broad questions like 'what was I doing?' (use activity-summary, it pre-summarizes apps + windows + transcripts). Also DO NOT USE for: targeted UI controls (use search-elements). Start with limit=5, increase only if needed. Per-result text is auto-truncated to 1000 chars; pass max_content_length=0 to opt out, or a custom integer to override.
- **synced-devices** — List this signed-in user's Screenpipe devices that have uploaded Data Sync records, including each device name and last sync time. USE WHEN: the user asks what devices are available, names another device, or asks a cross-device question and you need the exact device_name filter. This never accepts an account or bucket identifier; the local app forwards the signed-in user's identity.
- **search-synced-content** — Search Data Sync records from this signed-in user's devices. Results include device name, device ID, and timestamp for attribution. USE WHEN: the user asks about another/named device, asks across devices, or local search does not cover the requested machine. For the current machine only, use search-content. Start with a narrow time range and limit=10.
- **list-meetings** — List detected meetings (Zoom, Teams, Meet, etc.) with id, duration, app, attendees, and note status. Pass `q` to substring-match title, attendee names/emails, and notes — `q` searches ALL meeting history, so when looking for a meeting with a person or on a topic ('when did I last talk to Noah?'), pass `q` and OMIT start_time. Only constrain the time range when the question itself is time-bound. Results are newest-first; without `q`, old meetings only surface via time range or offset pagination. Follow up with get-meeting (id from results) for the full note and transcript.
- **activity-summary** — Rich activity overview: authoritative active minutes, app/window time, edited document paths, key text, and audio transcriptions, with optional parsed task context when available. USE WHEN: any broad question about what the user did — 'what was I doing?', 'how long on X?', 'which apps?', 'recap my morning'. This is almost always the right first call for time-range questions — usually sufficient without follow-up searches. Use parsed/path evidence to identify tasks, but only active-minute fields for duration; frame and row counts are never time. DO NOT USE for: finding a specific keyword (use keyword-search) or a specific UI control (use search-elements).
- **search-elements** — Search UI elements (buttons, links, text fields) from the accessibility tree, filterable by role. USE WHEN: you want a specific UI control or page-structure question — 'find every Submit button I saw', 'list the links in that page'. DO NOT USE for: general text/content (use search-content) or fast keyword lookup (use keyword-search).
- **frame-context** — Get full accessibility text, parsed tree nodes, and URLs for a specific frame ID. Use after search-content to get detailed context for a specific moment.
- **export-video** — Export an MP4 of screen recordings for a time range, with synced microphone audio. Frames are placed at their real timestamps, so the clip's duration matches the wall-clock span you requested (not a sped-up timelapse). Returns the file path. Can take a few minutes for long ranges.
- **update-memory** — Create, update, or delete a persistent memory (facts, preferences, decisions the user wants to remember). To retrieve memories, use search-content with content_type='memory'. To create: provide content + tags. To update: provide id + fields to change. To delete: provide id + delete=true.
- **get-feedback** — Search local user ratings and written comments attached to AI-produced notifications, chats, memories, blocks, artifacts, and other targets. Use before generating related work so you preserve what earned up ratings and correct what earned down ratings.
- **send-notification** — Send a notification to the screenpipe desktop UI. Use high priority only for time-sensitive failures or decisions needing human attention; routine findings and completed tasks should be normal or low.
- **health-check** — Check if screenpipe is running and healthy. Returns recording status, frame/audio stats, timestamps.
- **list-audio-devices** — List available audio input/output devices for recording.
- **list-monitors** — List available monitors/screens for capture.
- **add-tags** — Tag a screen frame (vision) or audio chunk (audio) so it can be retrieved later. Tags are a shared linking layer: use namespaced tags (person:ada, project:atlas, topic:pricing) to connect a capture to a person, project, or topic. The SAME tag string also works on memories (via update-memory), so tagging a frame and a memory with person:ada links them. Retrieve later with search-content tags='person:ada' (add content_type+start_time/end_time to scope to a timeframe). Note: frames are pruned by retention, so for durable links prefer tagging a memory; tag frames/audio for shorter-term recall.
- **search-speakers** — Search for speakers by name prefix. Returns speaker ID, name, and metadata.
- **list-unnamed-speakers** — List speakers that haven't been named yet. Useful for speaker identification workflow.
- **update-speaker** — Rename a speaker or update their metadata.
- **merge-speakers** — Merge two speakers into one (e.g. when the same person was detected as different speakers).
- **start-meeting** — Manually start a meeting recording session.
- **stop-meeting** — Stop the current manual meeting recording session.
- **get-meeting** — Get a meeting by ID: title, attendees, times, and the full note. Pass include_transcript=true to also get the speaker-attributed transcript segments — do this when the note is empty and you need to reconstruct what was said (much better than searching raw audio by time range).
- **update-meeting** — Update a meeting's mutable fields (title, attendees, note, app, start/end). Partial: only the fields you pass are written, others stay as-is. Use this to save an AI-generated summary into the meeting note — read the current note first via get-meeting and pass the existing notes plus your additions so you don't overwrite the user's writing. Convention: append AI-generated summary text under a `## Summary` heading at the bottom of the existing note.
- **keyword-search** — Fast FTS5 keyword search across OCR + audio combined. Returns matches with frame_id, app, timestamp, and text positions. USE WHEN: you have a specific keyword/phrase and want the fastest hit-list (e.g. 'find every screen where I typed "stripe"'). DO NOT USE for: structured filters by content_type / speaker / window — this endpoint ignores those (use search-content instead). DO NOT USE for: broad questions like 'what was I doing' (use activity-summary).
- **get-frame-elements** — Get all UI elements for a specific frame. More targeted than search-elements when you already have a frame_id.
- **control-recording** — Start or stop audio recording. This does not pause or resume screen capture.
- **list-pipes** — List the user's pipes (scheduled AI automations) with their enabled state + schedule. USE WHEN: the user asks what automations/pipes exist, or before you create or edit one.
- **create-pipe** — Create a pipe — a scheduled AI automation that runs a markdown prompt on a schedule (e.g. 'every day at 9am'). Writes ~/.screenpipe/pipes/<name>/pipe.md, installs it, enables it, and (by default) runs it once to test. USE WHEN: the user wants to automate a recurring task (daily summary, reminder, report, monitor, sync). IMPORTANT: read the screenpipe://guide/pipes resource FIRST — it documents the prompt format, schedule syntax, presets, and how the pipe prompt should query screenpipe. After creating, check pipe-logs to confirm the test run worked.
- **run-pipe** — Run a pipe once immediately (a test run), independent of its schedule. USE WHEN: you just created/edited a pipe and want to verify it, or the user says 'run X now'. Then read pipe-logs to see what it did.
- **pipe-logs** — Get a pipe's recent execution logs / output. USE WHEN: debugging why a pipe misbehaved, or reading the result of a test run.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "screenpipe": {
    "command": "npx",
    "args": ["-y","screenpipe-mcp@latest"],
    "env": {
      "SCREENPIPE_LOCAL_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `SCREENPIPE_LOCAL_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What Screenpipe does

Screenpipe provides local-first workflow memory for AI agents by continuously recording and indexing desktop screen and audio activity on your computer. Through its Model Context Protocol (MCP) server, AI assistants--such as Claude Desktop, Cursor, Windsurf, and Claude Code--can retrieve timestamped context, search past work, summarize conversations, and generate automated workflows grounded in actual user activity.

## How it works

Screenpipe operates as an on-device daemon that indexes desktop activity locally:

- **Screen capture**: Extracts text and UI state via the accessibility tree where available, falling back to OCR when needed.
- **Audio capture**: Records system and microphone audio, providing local transcription via Whisper or optional cloud transcription.
- **Local storage**: All captured frames, transcripts, and embeddings reside in a local SQLite database on your machine by default.
- **MCP server bridge**: The `screenpipe-mcp` package runs locally to safely answer queries from connected AI agents without exposing the raw database directly.

## Installation & Setup

### Recommended: Screenpipe Desktop Application

The most reliable and recommended installation path is via the desktop application:

1. Install the desktop app from [screenpipe.com](https://screenpipe.com).
2. Open **Settings > Connections** (or configure during onboarding).
3. Connect Claude Desktop.

This automatically configures Claude Desktop using Screenpipe's bundled runtime and injects your `SCREENPIPE_LOCAL_API_KEY` directly into the client configuration with zero external Node or PATH dependencies.

### Manual NPX Configuration

If you prefer configuring MCP manually or are connecting clients like Cursor or Windsurf, configure your client's MCP settings:

```json
{
  "mcpServers": {
    "screenpipe": {
      "command": "npx",
      "args": ["-y", "screenpipe-mcp@latest"],
      "env": {
        "SCREENPIPE_LOCAL_API_KEY": "YOUR_LOCAL_API_KEY"
      }
    }
  }
}
```

You can obtain your local API key anytime by running:
```bash
screenpipe auth token
```

## Available Tools

The standard stdio MCP package provides six core tools:

- `search_content`: Search captured screen recordings, OCR text, and audio transcriptions over arbitrary time windows.
- `export-video`: Export video clips from captured screen history.
- `list-meetings`: Inspect and retrieve detected meeting events and transcripts.
- `activity-summary`: Generate structured summaries of computer activity over a designated timeframe.
- `search-elements`: Search and inspect captured UI elements and accessibility tree items.
- `frame-context`: Retrieve frame context and OCR details for specific timestamps.

Orgs with enterprise query gateways can additionally configure `SCREENPIPE_ENTERPRISE_TOKEN` and `SCREENPIPE_TEAM_API_URL` to enable `team-*` org-wide search tools.

## Privacy, Security, and Licensing

- **Privacy by default**: Screenpipe stores all recordings, transcriptions, and indexes locally on your computer.
- **Cloud transmission**: Cloud AI, remote transcription (e.g. Deepgram), sync, and external integrations transmit data only if explicitly configured.
- **Model provider context**: When an AI assistant invokes Screenpipe tools, the retrieved snippet context is transmitted to the assistant's selected model provider as part of the prompt conversation.
- **License**: Screenpipe is source-available under the **Screenpipe Commercial License** (not OSI open source). Personal and non-commercial usage is free; commercial use requires a commercial license.

_Full upstream README: https://allmcps.com/mcp/screenpipe/readme_