# 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

```bash
npx local-secrets-mcp init
```

### 2. Add some secrets

```bash
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`):
```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):
```json
{
  "mcpServers": {
    "local-secrets": {
      "command": "npx",
      "args": ["-y", "local-secrets-mcp", "serve"]
    }
  }
}
```

**Custom database location** (use existing secrets folder):
```json
{
  "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

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