local-secrets-mcp

local-secrets-mcp

A simple MCP (Model Context Protocol) server for managing local secrets with Claude Code.

Store API keys, tokens, and other secrets locally and access them through Claude Code. Organize with categories and notes, import/export .env files, and manage everything via CLI or conversation.

Quick Start

1. Initialize the database

npx local-secrets-mcp init

2. Add some secrets

npx local-secrets-mcp add OPENAI_API_KEY sk-xxx
npx local-secrets-mcp add ANTHROPIC_API_KEY sk-ant-xxx --category ai
npx local-secrets-mcp add STRIPE_SECRET_KEY sk_live_xxx --category payments

3. Configure Claude Code

Add to your Claude Code MCP config:

For Claude Code CLI (~/.claude.json):

{
  "mcpServers": {
    "local-secrets": {
      "command": "npx",
      "args": ["-y", "local-secrets-mcp", "serve"]
    }
  }
}

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "local-secrets": {
      "command": "npx",
      "args": ["-y", "local-secrets-mcp", "serve"]
    }
  }
}

Custom database location (use existing secrets folder):

{
  "mcpServers": {
    "local-secrets": {
      "command": "npx",
      "args": ["-y", "local-secrets-mcp", "serve"],
      "env": {
        "SECRETS_PATH": "/path/to/your/.secrets"
      }
    }
  }
}

4. Use in Claude

Once configured, Claude can:

• List your secrets: "What API keys do I have stored?"
• Get a secret: "Get my OpenAI API key"
• Add secrets: "Store this Stripe key: sk_live_xxx"
• Search: "Find all my AI-related secrets"

CLI Commands

# Initialize database
local-secrets-mcp init

# Add a new secret
local-secrets-mcp add <key> <value>
local-secrets-mcp add GITHUB_TOKEN ghp_xxx --category github

# Add or update a secret
local-secrets-mcp set <key> <value>

# Get a secret value
local-secrets-mcp get <key>

# List all secrets
local-secrets-mcp list

# Delete a secret
local-secrets-mcp delete <key>

# Import from .env file
local-secrets-mcp import .env

# Export all secrets as .env format
local-secrets-mcp export > .env

# Show database path
local-secrets-mcp path

# Start MCP server (used by Claude Code)
local-secrets-mcp serve

Options

• --category, -c - Set category when adding/updating secrets
• --notes, -n - Add notes to a secret

MCP Tools

When connected to Claude Code, these tools are available:

Tool	Description
get_secret	Get a specific secret value by key
list_secrets	List all secret keys (optionally filter by category)
search_secrets	Search secrets by key name pattern
get_env_value	Get secret as environment variable format
add_secret	Add a new secret
update_secret	Update an existing secret
delete_secret	Delete a secret

Storage

Default location:

• Database: ~/.local-secrets/secrets.db
• Access log: ~/.local-secrets/access.log

Custom location: Set the SECRETS_PATH environment variable to use a different directory:

# CLI
SECRETS_PATH=~/.secrets npx local-secrets-mcp list

# Or export it
export SECRETS_PATH=~/.secrets
npx local-secrets-mcp list

Security Notes

• Local storage: Secrets are stored in a SQLite database on your machine only
• Conversation context: When Claude retrieves a secret, the value is included in the conversation and sent to Anthropic's servers (same as pasting a key into chat)
• No encryption: The local database is not encrypted - it relies on filesystem permissions
• Access logging: All access is logged to ~/.local-secrets/access.log
• Development use: This is designed for local development, not production secrets management

To keep secrets fully local: Use the CLI directly (npx local-secrets-mcp get MY_KEY) - this prints to your terminal and never touches the network. Only use Claude to retrieve secrets you're comfortable having in the conversation.

Requirements

• Node.js 22.0.0 or later (required - uses Node's native SQLite module)
• macOS, Linux, or Windows

License

MIT