local-kms-mcp-server

Local-first, lightweight MCP server for per-agent key management.

Give every agent its own signing identity - without relying on external KMS or exposing private keys.

local-kms-mcp-server generates, stores, rotates, and uses signing keypairs entirely on the local machine. Keys never leave the process, never touch the network, and stay under control.

It’s built for MCP clients and agent runtimes that need isolated, composable identities for tasks such as DID/SSI flows, auth handshakes, challenge signing, and any workflow where agents must prove something cryptographically

What It Does

• Generates signing keypairs scoped to a keyId (one identity per agent or task)
• Stores keys locally using a simple file-based keystore
• Rotates keys safely while preserving algorithm consistency
• Signs base64 payloads without ever exposing private key material
• Optionally encrypts keys at rest using AES-256-GCM
• Runs over MCP via stdio (default) or HTTP when needed

Supported Algorithms

Tool Reference

All tool inputs are validated with Zod. Public keys and signatures are returned as base64 strings.

Notes:

• generate_key fails if the keyId already exists
• rotate_key increments the stored version
• sign_message expects message to already be base64-encoded
• sign_message accepts an optional algo override, but in normal usage the stored algorithm is usually what you want

Storage Model

Unencrypted keys are stored as one file per key under ${STORE_PATH}:

${STORE_PATH}/${keyId}.json

Stored records contain:

{
  "keyId": "key-1",
  "algo": "ed25519",
  "publicKey": "...",
  "privateKey": "...",
  "version": 1,
  "createdAt": "2026-04-18T12:34:56.000Z"
}

When ENCRYPT_STORE=true, the file contents are encrypted and persisted as base64 ciphertext instead of plaintext JSON.

Security Notes

• Private keys never leave the server through MCP responses
• Key files are written with 0600 permissions
• At-rest encryption is optional but recommended for anything beyond throwaway local development
• HTTP mode does not add authentication or TLS by itself; keep it behind a trusted local boundary or your own reverse proxy
• keyId values become filenames, so use stable, filesystem-safe IDs

Development

pnpm install
pnpm build
pnpm test
pnpm lint
pnpm format:check

Run locally after building:

pnpm start

Watch the built output during development:

pnpm start:dev

Extending With New Algorithms

1. Implement a new adapter by extending KeyAlgorithmAdapter
2. Register it in src/keystore/index.ts
3. Expose the adapter name through the relevant tool schema if users should be able to select it

import { KeyAlgorithmAdapter } from '../adapter.js';
import type { KeyPair } from '../types.js';

export class MyAdapter extends KeyAlgorithmAdapter {
  readonly name = 'my-algo';

  generate(): KeyPair {
    /* ... */
  }

  sign(privateKey: string, data: Buffer): string {
    /* ... */
  }

  verify(publicKey: string, data: Buffer, signature: string): boolean {
    /* ... */
  }

  rotate(_currentKeyPair: KeyPair): KeyPair {
    return this.generate();
  }
}

Project Layout

src/
  config/               environment parsing and validation
  keystore/             adapters, registry, and file-based storage
  tools/                MCP tool registration and handlers
  utils/                crypto helpers, errors, serializers
  server.ts             MCP server construction
  main.ts               stdio and HTTP entry point
test/                   unit tests

Requirements

• Node.js >=24.0.0
• An MCP client that supports stdio or HTTP MCP servers

Quick Start

Stdio transport

Use stdio when running from Claude Desktop, Cursor, or another local MCP client.

{
  "mcpServers": {
    "local-kms": {
      "command": "npx",
      "args": ["-y", "local-kms-mcp-server"],
      "env": {
        "STORE_PATH": "/Users/yourname/.local-kms",
        "ENCRYPT_STORE": "true",
        "STORE_ENCRYPTION_KEY": "<base64-32-byte-key>"
      }
    }
  }
}

HTTP transport

Use HTTP only when you explicitly want a local network endpoint.

TRANSPORT=http PORT=8080 npx local-kms-mcp-server

Endpoint:

POST http://localhost:8080/mcp

Installation

Run directly with npx:

npx -y local-kms-mcp-server

Or install globally:

npm install -g local-kms-mcp-server
local-kms-mcp-server

Configuration

For local development there is an example file at .env.example, but for actual MCP client usage it is better to pass values through the client's env configuration so startup is deterministic.

Generate an encryption key:

node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"

Typical Usage Flow

1. Call generate_key for a new keyId
2. Call get_key_info to retrieve the public key for registration or distribution
3. Call sign_message whenever the agent needs to sign a challenge or payload
4. Call rotate_key when you need new key material for the same keyId
5. Call check_keypair or list_keys for inventory and existence checks

Example sign_message payload:

{
  "keyId": "key-1",
  "message": "eyJub25jZSI6IjEyMyJ9"
}

License

MIT