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

• Signs base64 payloads without ever exposing private key material

• Rotates keys safely while preserving algorithm consistency

• Deletes keys with optional secure wipe (overwrite with random data)

• Lists available signing algorithms and keys

• Optionally encrypts keys at rest using AES-256-GCM

• Runs over MCP via stdio (default) or HTTP when needed

Related MCP server: Agent Identity MCP Server

Supported Algorithms

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'))"

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

• delete_key with secureWipe: true overwrites the key file with random data before deletion

• 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

Typical Usage Flow

1. Call list_algorithms to see available signing algorithms

2. Call generate_key for a new keyId

3. Call get_key_info to retrieve the public key for registration or distribution

4. Call sign_message whenever the agent needs to sign a challenge or payload

5. Call rotate_key when you need new key material for the same keyId

6. Call delete_key to securely remove a keypair when no longer needed

7. Call check_keypair or list_keys for inventory and existence checks

Example sign_message payload:

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

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

License

MIT