plintho-mcp

A small CLI + MCP server that lets any MCP-capable client (Claude Desktop, Cursor, Cline, Zed, …) query the plintho voice-journal backend on behalf of a single user.

Install

pipx install plintho-mcp          # recommended
pip  install plintho-mcp          # alternative

Or from source:

git clone https://github.com/vtech-ai/plintho-mcp.git
cd plintho-mcp
pipx install -e .

Requires Python 3.11+. Runtime deps: mcp, httpx. The package does not pull in any of the plintho backend's heavy dependencies.

Pair this device with your account

$ plintho-mcp login --name "MacBook Cursor"
配对码: WXYZ-2345
请在 plintho iOS app → Settings → MCP Access 输入此码
等待中...
✓ 已登录为 user-abc

The token is saved to ~/.plintho/mcp_token (mode 600). The plaintext exists only on this machine; the server stores only its sha256 hash.

Wire into your MCP client

Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "plintho": { "command": "plintho-mcp" }
  }
}

Claude Code

claude mcp add plintho -- plintho-mcp

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "plintho": { "command": "plintho-mcp" }
  }
}

Same command key works for Cline / Zed / Continue / any stdio-MCP client.

Tools exposed

All tools are scoped to the user the token was issued to — there is no user_id parameter and the server enforces ownership on every call.

Collect local chat transcripts

plintho-mcp collect ships your Claude Code (~/.claude/projects) and OpenClaw (~/.openclaw/agents) conversations to your plintho account so they show up as chat events next to your voice notes. Only text blocks are uploaded — tool calls, tool results and thinking stay on your machine.

plintho-mcp collect                    # one incremental run (same as `collect run`)
plintho-mcp collect --dry-run          # parse only, print what would upload
plintho-mcp collect install            # macOS: launchd job every 5 min
plintho-mcp collect status             # heartbeat + launchd last exit code
plintho-mcp collect uninstall

It reuses the token from plintho-mcp login; the server binds every message to that token's owner, so there is no --user-id to get wrong.

Progress is tracked per file in ~/.plintho/collector_state.json (the first run imports offsets from the retired vmate ~/.vmate/chat_collector_state.json if present). Each run writes ~/.plintho/collector_last_run.json; collect status exits non-zero when the last run failed, the launchd job last exited non-zero, or the heartbeat is stale.

The launchd plist points at the absolute path of the installed plintho-mcp binary, so the job keeps working regardless of shell PATH or which Python environments come and go.

Optional — upload a session the moment it ends via a Claude Code SessionEnd hook (launchd still catches anything missed):

{ "hooks": { "SessionEnd": [ { "hooks": [
  { "type": "command", "command": "plintho-mcp collect --file \"$transcript_path\"" }
] } ] } }

Cloud sessions (claude.ai/code) don't write to ~/.claude/projects and are not collected.

Other commands

plintho-mcp whoami             # show current user_id / token name
plintho-mcp logout             # delete the local token file
plintho-mcp login --force      # re-pair (replaces existing token locally)

To revoke a token server-side, use the iOS app → Settings → MCP Access.

Environment variables