cryptoseed-mcp

MCP server for CryptoSeed encryption. Gives any MCP-compatible AI agent the ability to encrypt and decrypt text and files using ChaCha20-Poly1305 (symmetric) and X25519+HKDF (asymmetric), and sign/verify with Ed25519.

Keys are stored in the system Keychain (macOS Keychain, Windows Credential Manager, Linux SecretService) — never on disk in plain text. Encrypted .seed files are fully compatible with the CryptoSeed iOS app.

Supports stdio (local, default) and HTTP/HTTPS (remote agents) transports.

Requirements

| Platform | Requirement | |---|---| | macOS | Node.js >= 18. Keychain built-in. | | Linux | Node.js >= 18 + libsecret + active GNOME/KDE Keyring session. | | Windows | Node.js >= 18. Windows Credential Manager built-in. |

Setup

macOS — Claude Desktop (stdio, recommended)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cryptoseed": {
      "command": "npx",
      "args": ["-y", "cryptoseed-mcp"]
    }
  }
}

Restart Claude Desktop. All 24 CryptoSeed tools will appear automatically.

macOS — Claude Code (CLI)

claude mcp add cryptoseed -- npx -y cryptoseed-mcp

Verify with claude mcp list.

Linux — setup

# 1. Install Node.js 20+
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# 2. Install libsecret (required by keytar for GNOME/KDE Keyring)
# Ubuntu / Debian:
sudo apt install -y libsecret-1-dev
# Fedora / RHEL:
sudo dnf install -y libsecret-devel

# 3. Install
npm install -g cryptoseed-mcp

The GNOME/KDE Keyring must be running — it starts automatically with your desktop session.

Config for Claude Desktop on Linux (~/.config/Claude/claude_desktop_config.json):

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

Windows — setup

# 1. Install Node.js 18+ (uses Windows Credential Manager, no extra deps)
winget install OpenJS.NodeJS.LTS

# 2. Install
npm install -g cryptoseed-mcp

Config for Claude Desktop on Windows (%APPDATA%\Claude\claude_desktop_config.json):

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

HTTP / HTTPS transport (remote agents)

Run cryptoseed-mcp as a standalone HTTP server so any MCP-compatible agent can connect over the network.

# HTTP — development / local network only (no TLS)
npx cryptoseed-mcp --http
npx cryptoseed-mcp --http 8080

# HTTPS — production (requires TLS certificate)
npx cryptoseed-mcp --https 3443 --cert /path/to/fullchain.pem --key /path/to/privkey.pem

# Optional flags
#   --token <secret>   use a fixed bearer token instead of auto-generating one
#   --bind  <addr>     bind address (default: 0.0.0.0)

At startup, the server prints the bearer token to stderr:

[cryptoseed-mcp] Bearer token: a3f8c2e1d9b4f7e2...  (64 hex chars)
[cryptoseed-mcp] Listening on https://0.0.0.0:3443/mcp

Every agent that connects must include Authorization: Bearer <token> in its requests.

TLS certificate — quick options

# Let's Encrypt (recommended for production)
certbot certonly --standalone -d mcp.yourdomain.com

# Self-signed (local testing only — most MCP clients will reject it)
openssl req -x509 -newkey rsa:2048 \
  -keyout key.pem -out cert.pem \
  -days 365 -nodes -subj "/CN=localhost"

Security notes

• Use --https for any traffic over the internet. --http exposes the bearer token in plaintext.
• The bearer token is a shared secret. All connected agents share it.
• Private keys never leave the server's system Keychain — only aliases and ciphertexts travel over the network.
• Tools that accept file paths (encrypt_file, decrypt_file, sign_file, verify_file, contact_export, contact_import) accept arbitrary paths. Restrict server access accordingly when exposing over HTTP.

Connecting agents to the HTTP server

Claude Desktop (remote MCP)

{
  "mcpServers": {
    "cryptoseed": {
      "url": "https://mcp.yourdomain.com:3443/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Anthropic Agent SDK (Node.js)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const response = await client.beta.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 1024,
  tools: [{ type: "mcp", server_name: "cryptoseed" }],
  mcp_servers: [
    {
      type: "url",
      url: "https://mcp.yourdomain.com:3443/mcp",
      name: "cryptoseed",
      authorization_token: "<token>",
    }
  ],
  messages: [{ role: "user", content: "Create an identity called 'agent-a' and give me its public key" }]
});

LangChain / Python

from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent

async with MultiServerMCPClient({
    "cryptoseed": {
        "url": "https://mcp.yourdomain.com:3443/mcp",
        "transport": "streamable_http",
        "headers": {"Authorization": "Bearer <token>"}
    }
}) as client:
    tools = client.get_tools()
    agent = create_react_agent("claude-opus-4-6", tools)
    result = await agent.ainvoke({"messages": "Encrypt this message for contact 'agent-b'"})

Manus / Kodex / other autonomous agents

Any agent with MCP Streamable HTTP support. Use these values in their MCP config:

| Field | Value | |---|---| | Transport | streamable-http | | URL | https://mcp.yourdomain.com:3443/mcp | | Auth header | Authorization: Bearer <token> |

If the agent only supports stdio (local launch), use command: npx -y cryptoseed-mcp instead.

Tools

Key management (symmetric)

| Tool | Description | |------|-------------| | key_new | Generate a 256-bit ChaCha20 key, save to Keychain | | key_list | List saved key aliases |

Identity management (asymmetric encryption)

| Tool | Description | |------|-------------| | identity_new | Generate an X25519 keypair, save private key to Keychain | | identity_pubkey | Return public key as base64 (share with senders) | | identity_list | List saved identity aliases |

Contacts (address book)

| Tool | Description | |------|-------------| | contact_add | Add a contact with their public key | | contact_update | Update contact metadata (channels, notes) | | contact_info | Show contact details | | contact_list | List all contacts | | contact_pubkey | Get a contact's public key as base64 | | contact_remove | Remove a contact | | contact_key_add | Add an additional key to a contact | | contact_export | Export all contacts to a portable bundle | | contact_import | Import contacts from a bundle |

Encrypt

| Tool | Description | |------|-------------| | encrypt_text | Encrypt text with a symmetric key → base64 | | encrypt_file | Encrypt a file → .seed file (CryptoSeed-compatible) | | encrypt_asym | Encrypt a message to a recipient's public key → base64 blob |

Decrypt

| Tool | Description | |------|-------------| | decrypt_text | Decrypt base64 ciphertext with a symmetric key | | decrypt_file | Decrypt a .seed file, restore original | | decrypt_asym | Decrypt a message encrypted to your identity |

Signing keys (Ed25519)

| Tool | Description | |------|-------------| | signing_key_new | Generate an Ed25519 signing keypair, save to Keychain | | signing_key_list | List saved signing key aliases | | signing_key_pubkey | Return signing public key as base64 |

Sign / Verify

| Tool | Description | |------|-------------| | sign_text | Sign text, return a CSS-SIG-1 JSON proof | | sign_file | Sign a file, return a CSS-SIG-1 JSON proof | | verify_text | Verify a CSS-SIG-1 proof for text | | verify_file | Verify a CSS-SIG-1 proof for a file |

Agent-to-agent encrypted messaging

Two agents on different machines, both running cryptoseed-mcp (any transport):

Agent A                                     Agent B
  |                                             |
  identity_new("agent-a")      identity_new("agent-b")
  identity_pubkey("agent-a") → contact_add("agent-a", pubkeyA)
  contact_add("agent-b", pubkeyB) ← identity_pubkey("agent-b")
  |                                             |
  encrypt_asym(contact="agent-b", text="secret")
  ——— ciphertext ———→ (any insecure channel) ——→ decrypt_asym("agent-b", ciphertext)
                                                 → "secret"

Only the agent holding the private key in its Keychain can decrypt. The ciphertext can travel through any channel — email, Slack, GitHub, another AI tool — without being readable.

File format compatibility

.seed files produced by this MCP server use the exact same binary format as:

• CryptoSeed iOS app
• cryptoseed macOS CLI

A file encrypted here can be decrypted in the iOS app (after importing the key) and vice versa.

Key transfer between tools

This MCP server and the cryptoseed CLI use separate Keychain entries (to avoid binary format conflicts). To use a key from the CLI in the MCP server, use the CLI's export/import commands:

cryptoseed key export mykey    # → recovery envelope (base64)
# then in Claude: import the envelope via key_new or a future key_import tool