mcp-keyring-injector

MCP Keyring Injector

Session-scoped credential management for Claude Code MCP servers. API keys are automatically injected from your OS keyring at startup and removed at exit - credentials exist in config files only while Claude Code runs.

The Problem

MCP servers in Claude Code require API keys in their environment configuration (~/.claude.json). Storing API keys in config files is a security risk:

• Keys are in plaintext on disk
• Easy to accidentally commit to git
• Shared across all projects
• Hard to rotate without editing configs

The Solution

This plugin solves the problem by:

1. Storing API keys in your system keyring (encrypted)
2. Dynamically injecting them into ~/.claude.json when Claude Code starts (SessionStart hook)
3. Automatically removing them when the session ends (SessionEnd hook)
4. Working cross-platform (Linux, macOS, Windows)

Keys exist in config files only while Claude Code is running - true session-scoped security!

Features

• Secure: Keys stored encrypted in system keyring
• Cross-platform: Works on Linux (GNOME Keyring), macOS (Keychain), Windows (Credential Manager)
• Automatic: Runs on every Claude Code session start
• Flexible: Configure multiple MCP services from one file
• Minimal overhead: Negligible performance impact on session startup

Installation

1. Install the plugin

# Via Claude Code plugin system
/plugin marketplace add astrogilda/claude-plugins
/plugin install mcp-keyring-injector

# Or manually
git clone https://github.com/astrogilda/mcp-keyring-injector.git ~/Documents/mcp-keyring-injector

2. Install Python dependencies

uv pip install keyring

3. Store your first API key

Choose your platform:

Linux (GNOME Keyring):

python3 -c "import keyring; keyring.set_password('github', 'api-key', 'YOUR_API_KEY')"

macOS (Keychain):

security add-generic-password -s github -a api-key -w YOUR_API_KEY

Windows (PowerShell):

cmdkey /generic:github /user:api-key /pass:YOUR_API_KEY

4. Configure MCP credentials

Create ~/.claude/config/mcp-credentials.json:

{
  "github": {
    "env_var": "GITHUB_TOKEN",
    "service": "github",
    "account": "api-key",
    "label": "GitHub API Token",
    "mcp_server": "github-mcp"
  }
}

See examples/mcp-credentials.json for more examples.

5. Verify it works

Restart Claude Code. You should see:

MCP credentials - Injected: GitHub API Token

Check your GitHub MCP tools are now available!

Upgrading from v1.0.0

If you're upgrading from v1.0.0, here's what changed in v1.1.0:

What's New

• SessionEnd cleanup hook: Credentials are now automatically removed when Claude Code exits
• Session-scoped security: Keys only exist in ~/.claude.json while Claude is running
• Enhanced status messages: Better feedback on cleanup operations

Migration Steps

1. Update the plugin (automatic if using plugin marketplace):

   /plugin update mcp-keyring-injector
   

2. One-time cleanup - Remove old credentials from config (they won't auto-cleanup):

   # Backup first
   cp ~/.claude.json ~/.claude.json.backup
   
   # Remove credentials manually from ~/.claude.json env sections
   # Or let them be removed on next session start
   

3. No config changes needed - Your mcp-credentials.json format remains the same

Breaking Changes

• None! This is a fully backwards-compatible security enhancement

What Happens After Upgrade

• Next session: Credentials injected at start (as before)
• New behavior: Credentials automatically removed at session end
• Keys always remain safe in your system keyring

Configuration

Config File Format

~/.claude/config/mcp-credentials.json:

{
  "service-name": {
    "env_var": "ENVIRONMENT_VARIABLE_NAME",
    "service": "keyring-service-name",
    "account": "keyring-account-name",
    "label": "Human Readable Label",
    "mcp_server": "mcp-server-name-in-claude.json"
  }
}

Fields:

• env_var: Environment variable the MCP server expects (e.g., GITHUB_TOKEN)
• service: Keyring service name (how you stored the key)
• account: Keyring account/username (how you stored the key)
• label: Display name in status messages
• mcp_server: MCP server name from ~/.claude.json (defaults to service-name if omitted)

Adding Multiple Services