Quick Start

No cloning required! Install directly via npm. Only clone if you want to contribute.

1. Install

npx vaultrunner setup
claude mcp add vaultrunner -s user -- npx -p vaultrunner vaultrunner-mcp

2. Install Claude for Chrome

Get it from the Chrome Web Store

3. Restart Claude Code

claude mcp list  # Should show vaultrunner

4. Start Automating

You: "Log into my AWS console"

Claude: Found 2 accounts. Which one?
        1. [email protected]
        2. [email protected]

You: "Use work"

Claude: Done! You're logged into AWS.

What It Does

| Feature | Description | |---------|-------------| | 1Password Integration | Fetches credentials via 1Password CLI | | Automatic 2FA | TOTP from 1Password, SMS from Messages, codes from Gmail | | Pattern Learning | Remembers successful login flows per site | | Account Preferences | Saves your default account per domain | | Dashboard | Web UI for login history and success rates |

How It Works

VaultRunner is an MCP server that gives Claude access to your 1Password credentials:

┌─────────────────────────────────────────────────────────────┐
│  You: "Log into GitHub"                                      │
│  ↓                                                           │
│  Claude: list_logins("github.com") → VaultRunner MCP         │
│  ↓                                                           │
│  VaultRunner: Queries 1Password CLI                          │
│  ↓                                                           │
│  Claude: get_credentials(item_id) → Gets username/password   │
│  ↓                                                           │
│  Claude for Chrome: Fills form, clicks login                 │
│  ↓                                                           │
│  If 2FA needed: get_totp() or get_2fa_code() from SMS/email  │
│  ↓                                                           │
│  Logged in!                                                  │
└─────────────────────────────────────────────────────────────┘

Requirements

Required

• Claude Max subscription — Required for Claude Code and Claude for Chrome
• Claude for Chrome — Chrome Web Store
• 1Password with CLI enabled (install guide)
• 1Password Desktop App — Required for biometric unlock and seamless CLI authentication
• Node.js 18+

Optional (for 2FA)

• macOS Messages — For SMS codes (requires Full Disk Access)
• Gmail — For email codes (requires Google OAuth)

Recommended Settings

1Password Chrome Extension

If you have the 1Password Chrome extension installed, it can interfere with Claude for Chrome's browser automation by showing autofill dropdowns that block form fields.

To fix this:

1. Right-click the 1Password extension icon in Chrome
2. Select "This Can Read and Change Site Data"
3. Change from "On all sites" to "When you click the extension"

This prevents 1Password from automatically showing dropdowns during automation while still letting you use it manually when needed. VaultRunner already handles credentials via the 1Password CLI, so you don't need the extension's autofill during automated logins.

MCP Tools

Credentials

| Tool | Description | |------|-------------| | get_vault_status | Check if 1Password is authenticated | | list_logins | List accounts for a domain | | get_credentials | Get username and password | | get_totp | Get TOTP code from 1Password |

2FA

| Tool | Description | |------|-------------| | get_2fa_code | Read codes from SMS or email |

Preferences

| Tool | Description | |------|-------------| | set_account_preference | Save default account per site | | get_account_preference | Get saved default | | clear_account_preference | Clear preference |

Tracking

| Tool | Description | |------|-------------| | report_login_outcome | Report success/failure | | get_login_pattern | Get learned pattern for a domain | | get_login_stats | View history and statistics |

CLI Commands

# Setup
npx vaultrunner setup              # Full setup wizard
npx vaultrunner status             # Check system status

# 2FA Configuration
npx vaultrunner setup-messages     # Configure SMS reading (macOS)
npx vaultrunner setup-gmail        # Connect Gmail for email 2FA
npx vaultrunner test-2fa           # Test 2FA code reading

# Dashboard & History
npx vaultrunner dashboard          # Launch web dashboard
npx vaultrunner stats              # View login statistics
npx vaultrunner history            # View recent login attempts

Troubleshooting

"Vault not authenticated"

1. Open 1Password Desktop App and unlock, OR
2. Run op signin in terminal

MCP not loading

1. Run claude mcp list to verify
2. Restart Claude Code
3. Check /mcp in Claude Code

2FA codes not found

• SMS: Run vaultrunner setup-messages and grant Full Disk Access
• Gmail: Run vaultrunner setup-gmail
• TOTP: Check that 1Password item has a one-time password

Dashboard

npx vaultrunner dashboard
# Opens http://localhost:19877

Tracks login attempts, success rates, 2FA types, and learned patterns.

Use Cases

• DevOps: AWS, GCP, Azure consoles
• Social Media: Twitter, LinkedIn
• SaaS: Salesforce, HubSpot, Zendesk
• E-commerce: Shopify, Amazon Seller
• Any authenticated workflow Claude couldn't do before

Development (Contributing)

For contributors only. Most users should use the Quick Start instead.

Do not mix npm and local builds. If you cloned the repo, use the commands below. Do not run npx vaultrunner from inside the cloned repo — it will fail.

git clone https://github.com/anon-dot-com/vaultrunner.git
cd vaultrunner && pnpm install && pnpm build

# Run setup (use local build, NOT npx)
node packages/mcp-server/dist/cli/index.js setup

# Add to Claude Code (use local build, NOT npx)
claude mcp add vaultrunner -s user -- node $(pwd)/packages/mcp-server/dist/index.js

License

MIT © Anonymity Labs, Inc.