# local-kms-mcp-server

[![npm version](https://badge.fury.io/js/local-kms-mcp-server.svg)](https://badge.fury.io/js/local-kms-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

## Supported Algorithms

| Algorithm       | Tool value         | Notes                                                    |
| --------------- | ------------------ | -------------------------------------------------------- |
| Ed25519         | `ed25519`          | Good default for general signing and DID-style use cases |
| ECDSA secp256k1 | `ecdsa-secp256k1`  | Common for Ethereum, Bitcoin, and other Web3 flows       |
| ECDSA P-256     | `ecdsa-prime256v1` | ES256, WebAuthn, and common cloud KMS compatibility      |
| ECDSA P-384     | `ecdsa-secp384r1`  | Higher-security NIST P-384 environments                  |

## 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.

```json
{
  "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.

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

Endpoint:

```text
POST http://localhost:8080/mcp
```

## Installation

Run directly with `npx`:

```bash
npx -y local-kms-mcp-server
```

Or install globally:

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

## Configuration

| Environment variable   | Default  | Description                                                    |
| ---------------------- | -------- | -------------------------------------------------------------- |
| `STORE_PATH`           | `./keys` | Directory used for persisted key files                         |
| `TRANSPORT`            | `stdio`  | MCP transport: `stdio` or `http`                               |
| `PORT`                 | `8080`   | HTTP port used only when `TRANSPORT=http`                      |
| `ENCRYPT_STORE`        | `false`  | Set to `true` or `1` to encrypt key files at rest              |
| `STORE_ENCRYPTION_KEY` | none     | Base64-encoded 32-byte key required when encryption is enabled |

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:

```bash
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.

| Tool              | Purpose                                               | Input                                           | Output                               |
| ----------------- | ----------------------------------------------------- | ----------------------------------------------- | ------------------------------------ |
| `check_keypair`   | Check whether a key exists                            | `{ "keyId": "agent-1" }`                        | `{ "exists": true }`                 |
| `list_keys`       | List all stored key IDs                               | `{}`                                            | `{ "keys": ["agent-1", "agent-2"] }` |
| `list_algorithms` | List all supported signing algorithms                 | `{}`                                            | `{ "algorithms": ["ed25519", ...] }` |
| `generate_key`    | Create and persist a new keypair                      | `{ "keyId": "agent-1", "algo": "ed25519" }`     | `{ "publicKey": "..." }`             |
| `get_key_info`    | Return the stored public key for a key ID             | `{ "keyId": "agent-1" }`                        | `{ "publicKey": "..." }`             |
| `rotate_key`      | Rotate an existing keypair using its stored algorithm | `{ "keyId": "agent-1" }`                        | `{ "newPublicKey": "..." }`          |
| `delete_key`      | Delete a keypair with optional secure wipe            | `{ "keyId": "agent-1", "secureWipe": true }`    | `{ "success": true }`                |
| `sign_message`    | Sign a base64-encoded payload                         | `{ "keyId": "agent-1", "message": "aGVsbG8=" }` | `{ "signature": "..." }`             |

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:

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

## Storage Model

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

```text
${STORE_PATH}/${keyId}.json
```

Stored records contain:

```json
{
  "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

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

Run locally after building:

```bash
pnpm start
```

Watch the built output during development:

```bash
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

```typescript
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

```text
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