op-mcp

1Password CLI(op)를 래핑하여 MCP 클라이언트(Cowork, Claude Code, Claude Desktop)에 비밀번호 액세스 및 항목 관리 기능을 제공하는 MCP 서버입니다.

아키텍처

MCP client (Cowork, Claude Code, Claude Desktop)
  ↓ stdio (MCP protocol)
op-mcp (this Python server)
  ↓ subprocess per tool call
op CLI (1Password CLI)
  ↓ biometric prompt (Touch ID) + 1Password desktop app
1Password vaults

이 Python 서버는 의도적으로 가볍게 설계되었습니다. 모든 도구 핸들러는 op CLI를 호출하여 JSON을 파싱하거나 원시 출력을 반환합니다. CLI는 생체 인증, 세션 캐싱 및 모든 보관함 액세스를 처리합니다. Python 측은 MCP 프로토콜 및 argv 구성을 처리합니다.

이 설계는 구조적으로 상태 비저장(stateless)입니다. 각 도구 호출은 새로운 CLI 프로세스를 생성합니다. op는 1Password 데스크톱 앱 내에서 자체 세션을 캐시하므로, 우리는 세션, 토큰 또는 자격 증명을 관리하지 않습니다. 전체 근거는 docs/design-notes.md를 참조하십시오.

사전 요구 사항

• Python 3.11 이상

• op CLI가 설치되어 있고 PATH에 있어야 합니다. Homebrew를 통해 설치: brew install --cask 1password-cli (v2.33.1에서 테스트됨).

• 1Password 데스크톱 앱이 설치되어 있고 CLI 통합이 활성화되어 있어야 합니다: 1Password → 설정 → 개발자 → ✓ "1Password CLI와 통합".

• CLI 승인을 위해 Touch ID가 활성화되어 있어야 합니다 (동일한 설정 창).

설치

uv tool install .

이 명령은 격리된 venv를 생성하고 op-mcp를 PATH에 추가합니다. 코드 변경 후 업그레이드하려면:

uv tool install --force --reinstall .

두 플래그가 모두 필요합니다. --force는 기존 실행 파일을 덮어쓰고, --reinstall은 빌드 캐시를 우회합니다.

실행

서버는 stdio를 통해 통신하므로 일반적으로 수동으로 호출하기보다는 MCP 클라이언트에 의해 실행됩니다. 로컬 스모크 테스트를 위해서는:

op-mcp

서버는 stderr에 로그를 기록하고 stdin에서 MCP 프로토콜 메시지를 기다립니다. 종료하려면 Ctrl-C를 누르십시오.

MCP 클라이언트 구성

Claude Desktop: 설정 → 커넥터 → 추가 → 명령어로 op-mcp를 입력합니다. 또는 claude_desktop_config.json을 직접 편집합니다:

{
  "mcpServers": {
    "op": {
      "command": "op-mcp"
    }
  }
}

Claude Code: 동일한 형식으로 .mcp.json(프로젝트) 또는 ~/.claude/mcp.json(전역)에 추가합니다.

Cowork: Cowork의 MCP 서버 구성을 통해 추가합니다.

권장 권한

읽기 권한은 허용해도 안전하지만, 쓰기 권한은 확인을 요청해야 합니다.

{
  "permissions": {
    "allow": [
      "mcp__op__op_ping",
      "mcp__op__op_version",
      "mcp__op__op_list_vaults",
      "mcp__op__op_get_item",
      "mcp__op__op_read_secret",
      "mcp__op__op_list_items"
    ],
    "ask": [
      "mcp__op__op_create_item",
      "mcp__op__op_edit_item",
      "mcp__op__op_delete_item"
    ]
  }
}

개발

uv sync --extra dev
uv run pytest                              # unit tests (fake `op` binary)
RUN_LIVE_OP_TESTS=1 uv run pytest -m live  # live tests against real op CLI
uv run ruff check
uv run pyright

테스트는 가짜 op 바이너리(임시 셸 스크립트)를 사용하므로 실제 CLI나 1Password 액세스가 필요하지 않습니다. 라이브 테스트(@pytest.mark.live로 표시됨)는 실제 CLI에 대해 실행되고 Touch ID를 트리거하며 기본적으로 건너뜁니다.

도구

총 9개의 도구: 인프라 2개, 읽기 4개, 쓰기 3개.

인프라

읽기 도구

쓰기 도구

현재 범위 제외 (추후 고려)

• op signin / op signout — 세션 관리는 op의 역할입니다.

• op document / op vault — 사용 사례가 생기면 추가합니다.

• op inject / op run — 템플릿 주입 및 환경 변수 로드 워크플로우는 깔끔한 MCP 대응 기능이 없는 명령줄 편의 기능입니다.

• 서비스 계정 토큰 — 이 서버는 생체 인식 데스크톱 인증을 가정합니다.