# GhostKey

> MCP-native credential vault — AI agents authenticate without holding secrets.

[![npm version](https://img.shields.io/npm/v/ghostkey)](https://www.npmjs.com/package/ghostkey)
[![npm downloads](https://img.shields.io/npm/dm/ghostkey)](https://www.npmjs.com/package/ghostkey)
[![CI](https://img.shields.io/github/actions/workflow/status/woodwosj/GhostShell/ci.yml?branch=main&label=CI)](https://github.com/woodwosj/GhostShell/actions)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-%E2%89%A522-green)](https://nodejs.org)

## What is GhostKey?

GhostKey is an MCP server that manages credentials on behalf of AI agents.
Agents never see raw secrets — they call MCP tools like `ghostkey_request` or
`ghostkey_connect`, and GhostKey injects the right authentication transparently.

- **Zero secret exposure** — agents authenticate without holding API keys,
  passwords, or tokens
- **7 auth patterns** — bearer, basic, API key header, custom header, XML-RPC,
  OAuth2, query parameter
- **Persistent connections** — managed PostgreSQL and XML-RPC/Odoo sessions
- **Works with any MCP client** — Claude Code, Claude Desktop, Cursor, VS Code,
  Gemini CLI, and more

## Tiers

| Feature | Local (Free) | Cloud Backup (Free) | Pro ($10/mo) | Enterprise |
|---------|:---:|:---:|:---:|:---:|
| Encrypted local vault | ✓ | ✓ | ✓ | ✓ |
| MCP stdio transport | ✓ | ✓ | ✓ | ✓ |
| Midnight cloud backup | — | ✓ | ✓ | ✓ |
| HTTP relay (remote agents) | — | — | ✓ | ✓ |
| Included ops/month | — | — | 5,000 | Unlimited |
| Cardano NFT ownership | — | — | ✓ | ✓ |
| Own wallet mode | — | — | ✓ | ✓ |
| Self-hosted proof server | — | — | — | ✓ |
| SSO / RBAC | — | — | — | ✓ |

## Install

```bash
npm install -g ghostkey
```

Or run without installing:

```bash
npx ghostkey
```

## Quick Start

```bash
# 1. Create a vault
ghostkey init

# 2. Register a credential
ghostkey register --id stripe --type bearer --base-url https://api.stripe.com

# 3. Configure your AI client
ghostkey setup

# 4. Agents use MCP tools — no secrets exposed
#    ghostkey_request { credential_id: "stripe", method: "GET", url: "/v1/charges" }
```

## MCP Client Configuration

Add GhostKey to your MCP client config:

```json
{
  "mcpServers": {
    "ghostkey": {
      "command": "npx",
      "args": ["-y", "ghostkey"]
    }
  }
}
```

**Config file locations:**
| Client | Config Path |
|--------|------------|
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Code | `~/.claude.json` |
| Cursor | `.cursor/mcp.json` in your project |
| VS Code (Copilot) | `.vscode/mcp.json` in your project |

## MCP Tools

| Tool | Description |
|------|-------------|
| `ghostkey_list` | List stored credentials, optionally filtered by tag, scope, or description |
| `ghostkey_status` | System status or detailed credential info with expiry warnings |
| `ghostkey_request` | Authenticated HTTP request using a stored credential |
| `ghostkey_connect` | Open a persistent connection (PostgreSQL or XML-RPC/Odoo) |
| `ghostkey_query` | Execute a query on an existing managed connection |

## Auth Patterns

| Type | Use Case |
|------|----------|
| `bearer` | REST APIs with Bearer tokens (Stripe, GitHub, etc.) |
| `basic` | HTTP Basic authentication (username:password) |
| `api_key_header` | APIs that use a custom header for the key (e.g., `X-API-Key`) |
| `custom_header` | Arbitrary header with a `{{secret}}` template |
| `xmlrpc` | XML-RPC services (Odoo `execute_kw` pattern) |
| `oauth2` | OAuth2 client credentials with automatic token refresh |
| `query_param` | Secret injected as a URL query parameter |

## Security

GhostKey is designed with defense-in-depth:

- **Argon2id** key derivation (password to 256-bit AES key)
- **AES-256-GCM** authenticated encryption for all stored credentials
- **SSRF prevention** — domain whitelisting per credential, private IP blocking
- **CRLF injection** — rejected in all header values
- **Error sanitization** — credentials never leak in error messages or MCP responses
- **Buffer zeroing** — best-effort secret wipe on shutdown
- **File permissions** — vault directory 700, credential file 600

### Privacy

- **No telemetry** — GhostKey collects zero usage data
- **No network calls** — in local vault mode, nothing leaves your machine
- **No cloud dependency** — works fully offline with local vault storage
- **Credentials never logged** — secrets are excluded from all error messages, MCP responses, and debug output
- **Your vault, your data** — vault files are standard AES-256-GCM encrypted files on your filesystem

## CLI Reference

| Command | Description |
|---------|-------------|
| `ghostkey init` | Create a new credential vault |
| `ghostkey register` | Add a new credential to the vault |
| `ghostkey list` | List credential metadata |
| `ghostkey status` | Show vault health status |
| `ghostkey rotate` | Update a credential secret |
| `ghostkey revoke` | Deactivate a credential |
| `ghostkey start` | Launch MCP server with stdio transport |
| `ghostkey setup` | Configure LLM clients to use GhostKey |

## Supported Clients

GhostKey auto-detects and configures itself for these MCP clients:

| Client | Auto-Setup | Transport |
|--------|-----------|-----------|
| Claude Desktop | `ghostkey setup` | stdio |
| Claude Code | `ghostkey setup` | stdio |
| Cursor | `ghostkey setup` | stdio |
| VS Code (Copilot) | `ghostkey setup` | stdio |
| Windsurf | `ghostkey setup` | stdio |
| Gemini CLI | Manual | stdio |
| Continue | Manual | stdio |
| Custom | Manual | stdio/SSE |

## License

MIT. Copyright (c) 2026 Loomworks Solutions LLC. See [LICENSE](LICENSE).