Integrations & API
Drive Clipwell from REST, WebSocket/SSE, MCP, or the CLI.
The daemon exposes the same history three ways. Default base URL is
http://127.0.0.1:8787 (override with CLIPWELL_URL; clients read CLIPWELL_API).
REST
# recent history (newest first)
curl http://127.0.0.1:8787/api/clipboard?limit=20
# page back in time
curl "http://127.0.0.1:8787/api/clipboard?limit=20&before=2026-06-14T00:00:00Z"
# aggregate counts (total / pinned / sensitive / per kind), optionally search-scoped
curl http://127.0.0.1:8787/api/clipboard/counts
curl "http://127.0.0.1:8787/api/clipboard/counts?q=github"
# search the whole history by text or alias (not just the newest page)
curl "http://127.0.0.1:8787/api/clipboard/search?q=github&limit=50"
# omit items marked sensitive, including their text and aliases, before applying limit
curl "http://127.0.0.1:8787/api/clipboard?limit=20&excludeSensitive=true"
curl "http://127.0.0.1:8787/api/clipboard/search?q=github&excludeSensitive=true"
# one item by its exact timestamp
curl "http://127.0.0.1:8787/api/clipboard/item/2026-06-14T00:00:00Z"
# settings, delete, clear
curl http://127.0.0.1:8787/api/clipboard/settings
curl -X POST http://127.0.0.1:8787/api/clipboard/delete -d '{"timestamp":"..."}'
curl -X POST http://127.0.0.1:8787/api/clipboard/clear
# non-destructive text override (empty text restores the original)
curl -X POST http://127.0.0.1:8787/api/clipboard/edit -d '{"timestamp":"...","text":"edited"}'The full machine‑readable contract is published at GET /openapi/v1.json and
checked into the repo at openapi/clipwell.v1.json.
Live updates (SSE / WebSocket)
Both emit a clipboard.changed event on every capture.
// Server-Sent Events
new EventSource("http://127.0.0.1:8787/api/clipboard/stream")
.onmessage = (e) => console.log("changed:", JSON.parse(e.data));
// WebSocket
new WebSocket("ws://127.0.0.1:8787/api/clipboard/ws")
.onmessage = (e) => console.log("changed:", JSON.parse(e.data));MCP (AI agents)
Clipwell speaks MCP two ways, with the same four tools — clipboard_recent,
clipboard_search, clipboard_get_text, and clipboard_clear.
1. Over HTTP/SSE, served by the daemon at /mcp (Streamable HTTP). No extra
process — point an HTTP-capable MCP client straight at it:
{
"mcpServers": {
"clipwell": { "url": "http://127.0.0.1:8787/mcp" }
}
}2. Over stdio, for clients that spawn a child process (e.g. Claude Desktop).
The mcp/ project is a small stdio server that proxies to the running daemon —
point the client at the built Clipwell.Mcp executable:
{
"mcpServers": {
"clipwell": { "command": "/path/to/Clipwell.Mcp" }
}
}Both expose the identical tool surface; the HTTP one talks to the history store
in-process, the stdio one proxies over REST.
Both omit items marked sensitive from clipboard_recent and clipboard_search,
including matches on a sensitive item's alias. clipboard_get_text refuses a
sensitive item. REST still returns full history unless excludeSensitive=true is
requested; trusted picker clients need the content to display and paste it.
CLI
clipwell list 20 # recent items
clipwell watch # live-stream changes
clipwell clear # wipe history