onepassword-mcp-server

1Password MCP Server

MCP server for interacting with 1Password via the CLI. Enables AI assistants to securely access and manage credentials stored in 1Password vaults.

Highlights

• Elicitation-based approval - Users are prompted for confirmation before credentials are revealed or items are created
• Configurable per-action - Enable/disable elicitation independently for read and write operations
• Item whitelisting - Pre-approve specific items to bypass elicitation prompts
• Secure credential access via 1Password CLI
• Service account authentication for automation
• Read and write operations for vaults and items
• Tool grouping for permission-based access control

Prerequisites

• 1Password CLI (op) - Must be installed and available in PATH

  • Installation instructions

• 1Password Service Account - Required for authentication

  • Create a service account

Capabilities

Tools

Tool	Group	Description
onepassword_list_vaults	readonly	List all accessible vaults
onepassword_list_items	readonly	List items in a specific vault
onepassword_get_item	readonly	Get item details (credentials require approval to reveal)
onepassword_get_item_metadata	readonly	Get item metadata (titles, fields, vault, tags) without secret values — no approval prompt
onepassword_list_items_by_tag	readonly	Find items by tag
onepassword_create_login	write	Create a new login credential (requires approval)
onepassword_create_secure_note	write	Create a new secure note (requires approval)
onepassword_share_item	write	Mint a share URL for an existing item (requires approval)
onepassword_create_api_credential	write	Create a new API Credential item (requires approval)

Resources

Resource	Description
onepassword://config	Server configuration and status (for debugging)

Tool Groups

Control which tools are available via the ENABLED_TOOLGROUPS environment variable:

Group	Description
readonly	Read-only operations (list, get)
write	Write operations (create)

Examples:

• ENABLED_TOOLGROUPS="readonly" - Only read operations (safer for most use cases)
• ENABLED_TOOLGROUPS="readonly,write" - Full access
• Not set - All tools enabled (default)

Quick Start

Installation

npx onepassword-mcp-server

Configuration

Set the required environment variable:

export OP_SERVICE_ACCOUNT_TOKEN="your-service-account-token"

Claude Desktop Configuration

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "onepassword": {
      "command": "npx",
      "args": ["-y", "onepassword-mcp-server"],
      "env": {
        "OP_SERVICE_ACCOUNT_TOKEN": "your-service-account-token",
        "ENABLED_TOOLGROUPS": "readonly"
      }
    }
  }
}

Restart Claude Desktop and you should be ready to go!

Environment Variables

Variable	Required	Description	Default
OP_SERVICE_ACCOUNT_TOKEN	Yes	1Password service account token	-
ENABLED_TOOLGROUPS	No	Comma-separated tool groups	All enabled
SKIP_HEALTH_CHECKS	No	Skip credential validation on start	false
DANGEROUSLY_SKIP_ELICITATIONS	No	Set to true to bypass ALL confirmation prompts (exposes all secrets)	not set (elicitation required)
OP_ELICITATION_READ	No	Prompt before revealing credentials	true
OP_ELICITATION_WRITE	No	Prompt before creating/sharing items	false
OP_WHITELISTED_ITEMS	No	Comma-separated item titles or IDs that bypass read elicitation	none

Security Considerations

• Startup safety check: The server refuses to start unless elicitation is configured (HTTP fallback URLs) or explicitly opted out via DANGEROUSLY_SKIP_ELICITATIONS=true. This prevents accidental carte blanche access to all secrets.
• Elicitation-based approval (reads): By default, get_item prompts the user for confirmation before revealing sensitive credentials. Reads expose existing secrets, so the prompt is on by default.
• No elicitation on writes by default: Write operations (create_login, create_secure_note, create_api_credential, share_item) do NOT prompt by default. Writes only create new items or mint share URLs for existing ones — they cannot overwrite or delete existing data via these tools — so the friction of a prompt isn't justified. Set OP_ELICITATION_WRITE=true to opt in to write confirmations.
• Service Account Token: Passed via environment variable, never logged
• CLI Arguments: Passwords for create operations are passed as CLI arguments (briefly visible in process list)
• Recommendation: Use readonly tool group unless write access is specifically needed

How Credential Approval Works

• By default, onepassword_get_item returns item metadata but shows [REDACTED] for sensitive fields
• The server prompts the user to approve credential access via elicitation
• Once approved, the full credentials are returned for that request
• Whitelisted items (via OP_WHITELISTED_ITEMS, matched by title or item ID) bypass the approval prompt entirely

Checking Existence Without Approval

onepassword_get_item_metadata is a metadata-only sibling of onepassword_get_item. It returns the same item shape (title, category, vault, tags, field labels, types, URLs, dates, plus non-sensitive field values) but strips the values of sensitive fields entirely — no [REDACTED] placeholder, no leak — and never triggers an approval prompt. Reach for it when you only need to answer "does an item with title X exist in vault Y?" or "which fields does this item have?". Call onepassword_get_item only when you actually need to read a credential value.

Configuration Examples

Disable all confirmations (fully automated workflows):

DANGEROUSLY_SKIP_ELICITATIONS=true

Only confirm writes, auto-approve reads (requires HTTP fallback URLs for startup — DANGEROUSLY_SKIP_ELICITATIONS=true overrides per-action settings):

ELICITATION_REQUEST_URL="https://your-endpoint/request"
ELICITATION_POLL_URL="https://your-endpoint/poll"
OP_ELICITATION_READ=false
OP_ELICITATION_WRITE=true

Default behavior (prompt on reads, silent writes — recommended for most agent use cases):

ELICITATION_REQUEST_URL="https://your-endpoint/request"
ELICITATION_POLL_URL="https://your-endpoint/poll"
# OP_ELICITATION_READ defaults to true
# OP_ELICITATION_WRITE defaults to false

Whitelist specific items by title or ID (always auto-approve these):

OP_WHITELISTED_ITEMS="Stripe Key,AWS Credentials,abc123def456"

Development

Project Structure

onepassword-mcp-server/
├── local/                 # Local server implementation
│   └── src/
│       ├── index.ts      # Main entry point
│       └── index.integration-with-mock.ts
├── shared/               # Shared business logic
│   └── src/
│       ├── server.ts     # Server factory
│       ├── tools.ts      # Tool registration
│       ├── tools/        # Individual tools
│       ├── onepassword-client/  # CLI wrapper
│       └── types.ts      # TypeScript types
├── tests/                # Test suite
│   ├── functional/       # Unit tests
│   ├── integration/      # MCP protocol tests
│   └── manual/          # Real CLI tests
└── package.json

Running Locally

# Install dependencies
npm run install-all

# Build
npm run build

# Run tests
npm test

# Run integration tests
npm run test:integration

License

MIT