@cardgo/mcp

Use your CardGo cards from Claude, Cursor, and any other MCP client — without your cards ever leaving end-to-end encryption.

CardGo cards are encrypted in your browser before they sync, and the server can't read them. That is why this is a local MCP server: it runs on your machine, signs in as one more device on your account, and decrypts cards there. Nothing in plaintext ever reaches a CardGo server.

Requires a Pro or Max plan. Node.js 20.19 or newer.

Published as @cardgo/mcp. The unscoped cardgo-mcp is the same package under an older name and stays in step; new setups should prefer @cardgo/mcp.

Set up

1. In a terminal on the computer where you use your AI app:

   npx @cardgo/mcp connect

   This opens cardgo.ai (sign in and unlock your vault if asked) and shows an approval panel. Approve it; the terminal confirms within a second.

2. Add CardGo to your app.

   Claude Code

   claude mcp add cardgo -- npx -y @cardgo/mcp

   Claude Desktop — Settings › Developer › Edit config:

   { "mcpServers": { "cardgo": { "command": "npx", "args": ["-y", "@cardgo/mcp"] } } }

   Cursor — Settings › MCP › Add server (.cursor/mcp.json):

   { "mcpServers": { "cardgo": { "command": "npx", "args": ["-y", "@cardgo/mcp"] } } }

   Restart the app. Ask it something like "read my Work card before you answer" or "remember on my Apollo card that the launch moved to Friday".

What the AI gets

| Tool | Does | | ---------------- | ---------------------------------------------------------------------------- | | list_cards | Every card: id, name, breadcrumb, one-line summary. Call first. | | read_card | One card in full, plus the cards it is based on (a child inherits context). | | search_cards | Cards whose name or sections mention the query. | | create_card | A new card, optionally based on another. | | update_card | Change name, icon, colour, parent, or whole sections. | | append_to_card | Add one line to a section — the "remember that…" tool. | | delete_card | Permanently delete a card. |

Also: resources cardgo://cards and cardgo://cards/{id} (Markdown), and a use_cards prompt that loads cards as context.

Your AI app asks you before running a tool that changes a card. To hide the write tools entirely, run the server with --read-only (or set CARDGO_MCP_READ_ONLY=1):

{ "mcpServers": { "cardgo": { "command": "npx", "args": ["-y", "@cardgo/mcp", "--read-only"] } } }

Commands

cardgo-mcp connect [--name "My laptop"] [--no-browser]   enrol this machine
cardgo-mcp [serve] [--read-only]                          run the server (stdio)
cardgo-mcp status                                         what is connected
cardgo-mcp disconnect                                     revoke this device, forget the key

Security notes

• Where the key lives. ~/.cardgo/mcp.json (0600; override the directory with CARDGO_MCP_HOME) holds the session tokens and the raw vault key. Anything that can read that file can read your cards — the same trade the browser extension and the web app's "stay unlocked" make. Use cardgo-mcp disconnect, or Settings › Devices on cardgo.ai, to revoke.
• How the key gets here. The web app encrypts it to a P-256 key this process generated (ECDH → HKDF-SHA-256 → AES-256-GCM, bound to your account, key version, a one-time state, and the sign-in code) and redirects the browser to 127.0.0.1:<port>. Only the port comes from the link; the host is fixed, so the ciphertext can only land on the machine that started the flow.
• Revocation. Revoking the device ends its session immediately. Like every E2EE client, a revoked device keeps whatever key it already held; rotate your recovery code on cardgo.ai if a machine was compromised.
• Plan. Connecting needs Pro or Max. If the plan lapses, CardGo revokes MCP devices automatically.

Development

npm install
npm test             # protocol vectors shared with the web app, handoff, sanitisers
npm run dev -- status
npm run build        # dist/

src/crypto and src/cards mirror cardgo-lp/src/lib; src/test/card-vectors.test.ts proves the copy still decrypts what the web app encrypts.