screenpipe-mcp weekly downloads statistics

Screenpipe MCP Server

<a href="https://www.pulsemcp.com/servers/screenpipe-screenpipe"><img src="https://www.pulsemcp.com/badge/top-pick/screenpipe-screenpipe" width="400" alt="PulseMCP Badge"></a>

<br/>

https://github.com/user-attachments/assets/7466a689-7703-4f0b-b3e1-b1cb9ed70cff

MCP server for screenpipe - search your screen recordings, audio transcriptions, and control your computer with AI.

Usage attribution

When Screenpipe analytics are enabled, successful nonempty retrievals produce qualified_value_event with surface (api or mcp) and agent_client. Supported app identifiers are claude, chatgpt, codex, cursor, gemini, openclaw, hermes, runner, windsurf, vscode, grok, and grokbot. Claude Desktop and Claude Code share the existing claude bucket. This identifies the caller, not the app appearing in a recording.

MCP uses SCREENPIPE_MCP_CLIENT when it names a supported app, falling back to the initialization handshake's client name. HTTP sessions resolve independently. Only the fixed identifier is forwarded; raw client names are never analytics properties. Unrecognized MCP clients remain unknown.

Installed REST skills send X-Screenpipe-Client: api and a fixed X-Screenpipe-Agent header for their target app. Other API clients can send the same headers. Missing or unrecognized app identifiers retain the legacy direct_api bucket on qualified-value events. search_performed also includes the fixed agent_client (unknown when unidentified), alongside request_source. These are self-reported identifiers, not verified app identities; copied skills and callers that omit the headers cannot be reliably attributed. Historical generic API events cannot be assigned an app retroactively.

The engine preserves every existing uncached app, MCP and named-agent search_performed event. Only explicitly API-originated requests with an unknown agent are sampled: the first event per 60-second monotonic window per engine process, separately for empty/non-empty and parsed/ordinary results (at most four events per window, plus the first event in each category after UTC midnight to preserve daily activity). An empty background poll cannot consume the successful-result slot, and API traffic cannot consume an app, MCP or named-agent slot.

Sampled events carry telemetry_sampling: "first_per_interval_per_result_kind" and telemetry_sample_interval_seconds: 60; unsampled events carry "none" and 0. Sampled events are presence diagnostics, not exact search counts or an unbiased sample of query properties. Their counts and property breakdowns are not comparable to earlier releases. api_usage_5min.request_count still counts aggregate API traffic across all routes, and qualified_value_event retains the existing successful-retrieval path, including cached searches. No new events are added for cache hits. Health/resource telemetry and local monitoring retain their existing cadence.

Attribution adds fields to existing events and uses the existing analytics opt-out. It does not scan running apps or send prompts, search text, or raw client names. HTTP MCP now reports successful searches through the same best-effort local telemetry endpoint as stdio MCP; empty/failed searches do not produce qualified-value events.

Call diagnostics and source references

New engine builds accept POST /internal/telemetry/mcp-call through the same local API authentication and analytics consent boundary as other private MCP telemetry. mcp_tool_call_completed records one best-effort observation per completed dispatcher call: schema version, random request ID, package version, fixed client/tool/transport names, ok/empty/error, normalized error category, duration, content bytes, optional search count/truncation and known report loss. No arguments, result text, error strings or raw client names are included. The existing qualified_value_event definition is unchanged.

ok means the dispatcher returned without a protocol/tool error. It does not mean the answer was correct or the user completed their task. Search alone sets result_count and truncated; absent fields on other tools remain unknown. response_bytes counts UTF-8 text and base64 content bytes, not total serialized JSON or model tokens. Duration includes tool execution, excluding report delivery.

The request ID is returned in _meta["screenpipe/request_id"] and forwarded to the local API as x-screenpipe-request-id. It is one call's correlation key, not a user, session or task ID. This change does not add engine log persistence for that header. Local helpers report to the engine, which applies its telemetry opt-out. SCREENPIPE_DISABLE_TELEMETRY and SCREENPIPE_TELEMETRY_DISABLED also suppress call reporting; CI suppresses it by default. Delivery is capped at eight pending requests per reporter and expires after one second. Old engines, opt-out, backend outages and process exit can lose reports. dropped_reports reports known local losses on a later delivery, not complete observation coverage.

Screen/audio/input search results preserve backend source identifiers and deep links. Both package transports cap text at 1,000 characters per hit by default; max_content_length=0 requests full text for a scoped read. The cap excludes metadata, tags and images, so callers should also limit result count. Final pages do not suggest another offset. In stdio, pass a returned frame_id to frame-context or get-frame-elements to inspect evidence beyond the snippet. HTTP clients can open the returned Screenpipe link or make a narrower search. A missing source ID stays missing.…