1Password Agent MCP

1Password Agent MCP

Permita que agentes de IA usem e salvem segredos do 1Password por meio de um servidor MCP local, com um painel que coloca você no controle.

• Use segredos aprovados: agentes recebem identificadores criptografados. O servidor resolve e copia ou cola o campo selecionado localmente, sem retornar o texto simples ao agente.
• Salve segredos copiados: copie uma senha ou chave de API no seu navegador ou em um aplicativo local e deixe o servidor salvá-la no 1Password com argumentos de ferramenta contendo apenas metadados.
• Trabalhe sem supervisão: opte pela aprovação automática de novos itens e conecte uma conta de serviço 1Password com escopo para evitar solicitações repetidas de desbloqueio da área de trabalho.

pacote npm · guia de configuração · guia do usuário · modelo de segurança · guia de desinstalação

Projeto independente. Não afiliado ou endossado pela 1Password. Cada instalação usa suas próprias configurações locais e conta 1Password.

O painel atual, renderizado com itens de exemplo sintéticos. Todas as capturas de tela neste README usam dados de demonstração; nenhuma conta real, senha ou token de conta de serviço é exibido. Abrir captura de tela do Vault em tamanho completo.

Início Rápido

Você precisa de Node.js 20+, a CLI do 1Password (op) e um cliente MCP que suporte servidores stdio locais. Autentique usando a integração de área de trabalho do 1Password ou uma conta de serviço com escopo.

No macOS, instale os pré-requisitos se necessário:

brew install node 1password-cli

Para autorização da área de trabalho, abra 1Password → Configurações → Desenvolvedor e ative Integrar com a CLI do 1Password. Aprove apenas clientes em que você confia. A configuração da conta de serviço é descrita em Acesso sem supervisão.

Instale e execute o instalador guiado:

npm install -g onepassword-agent-mcp
onepassword-agent-mcp install

O instalador detecta clientes MCP suportados e pergunta antes de atualizar a configuração deles. No macOS, ele também oferece separadamente o atalho opcional visível na barra de menus.

Inicie o painel:

onepassword-agent-mcp admin

Abra http://127.0.0.1:7319. Para uma configuração manual, use onepassword-agent-mcp doctor e depois onepassword-agent-mcp setup all --apply.

Atualizando uma instalação existente? Execute npm install -g onepassword-agent-mcp@latest e reinicie o console administrativo e os clientes MCP existentes para que usem o novo código. Suas configurações locais, aprovações e chave de criptografia são mantidas.

Seu Painel

A barra lateral separa as quatro tarefas do dia a dia:

Dê a um Agente Sua Primeira Credencial

1. Abra Vault. Em Configuração do Vault do Agente, escolha Criar MCPVAULT se o vault dedicado não existir.
2. Em Escolher do 1Password, selecione um vault de origem, pesquise um item e clique em Copiar. Você também pode arrastá-lo para Aprovar Itens do Agente e escolher Copiar ou Mover.
3. Em Aprovar Itens do Agente, clique em Revisar Detalhes. Escolha os campos exatos a permitir e insira os sites onde os agentes podem usá-los.
4. Clique em Aprovar Selecionados. Os campos aprovados aparecem em Permitido para Agentes; use os controles Ativado, Salvar e Excluir para gerenciar o acesso.
5. No seu cliente MCP, peça ao agente para encontrar a credencial aprovada para o site atual e colá-la no campo pretendido.

Copiar mantém o item de origem. Mover remove-o do vault de origem após a transferência. Copiar um item para o vault do agente não o aprova. Uma lista de sites vazia permite todos os sites, então adicione um domínio quando o acesso deve ser limitado.

Os filtros de tipo—Todos os Campos, Logins, Chaves de API, Cartões de Crédito, Notas e SSH e Outros—facilitam a revisão de vaults maiores. Campos sensíveis, como CVV de cartão e PIN, não são sugeridos automaticamente durante a aprovação manual.

Para transferir uma credencial recém-salva de volta para outro vault, abra Revisar Detalhes → Salvar este item em outro vault. Copiar para Vault mantém o item do vault do agente; Mover para Vault remove-o do vault do agente e remove suas aprovações locais. Use o aplicativo 1Password para itens que contenham anexos, documentos ou chaves de acesso.

Escolha Quanto os Agentes Podem Fazer

Abra Permissões, escolha as configurações desejadas e clique em Salvar Configurações. As três opções abaixo estão desativadas em uma instalação nova.

Configuração de demonstração com as três permissões opcionais ativadas e status simulado de conta de serviço salva. O campo de token está vazio; o token salvo nunca é exibido. Abrir captura de tela de Permissões em tamanho completo.

A visualização Perfil é separada: os valores inseridos lá são intencionalmente legíveis pelos agentes por meio de get_profile_data. Não armazene senhas ou tokens como valores de perfil.

Salvar do Navegador ou Texto Selecionado

Em Permissões, ative Permitir que agentes salvem novos itens no MCPVAULT e Salvar segredos da área de transferência e clique em Salvar Configurações. Opcionalmente, ative a aprovação automática se os agentes devem poder usar novos itens imediatamente.

1. Em um navegador, clique no botão Copiar do segredo, ou selecione texto em um aplicativo local e use Copiar. O agente deve executar essa ação sem ler o campo, a área de transferência, o valor do DOM ou uma captura de tela que o revele.
2. Chame a ferramenta local apenas com metadados:

{
  "title": "Example account",
  "requestId": "example-signup-unique-id",
  "category": "login",
  "url": "https://example.com",
  "username": "my-login"
}

Use esses argumentos com save_secret_from_clipboard. As categorias suportadas são login, password, api_credential e secure_note. O texto é preservado exatamente, incluindo espaços e quebras de linha. A ferramenta é executada no computador que hospeda este servidor MCP e lê a área de transferência desse computador; a área de transferência de um navegador remoto é uma área de transferência diferente.

O aplicativo criptografa um instantâneo de nova tentativa localmente, utilizável por 15 minutos, passa o texto simples apenas pelo stdin da CLI local e verifica o item armazenado. A resposta contém metadados de salvamento e aprovação, nunca o texto copiado; use as ferramentas de busca/lista para identificadores criptografados aprovados. O texto cifrado expirado é removido enquanto o processo está em execução ou na próxima captura após inatividade; um registro apenas com metadados impede a reutilização de um ID de solicitação antigo. A limpeza da área de transferência reverifica se o valor não mudou e é melhor esforço; verifique o status de limpeza retornado. Gerenciadores de área de transferência podem manter seu próprio histórico.

Reutilize o mesmo requestId e metadados para tentar novamente. Uma nova tentativa usa a captura criptografada original mesmo se a área de transferência mudar. Uma captura expirada falha de forma segura em vez de capturar texto não relacionado; inspecione a operação anterior antes de iniciar intencionalmente uma nova solicitação. Metadados como títulos, nomes de usuário e URLs permanecem visíveis ao modelo: nunca coloque um segredo nesses campos. save_secret_item permanece disponível para valores já em contexto; não pode desfazer essa exposição.

Aprovação Automática

Em Permissões, ative Aprovar automaticamente itens criados por agentes e clique em Salvar Configurações. Esta opção fica desativada por padrão. A criação de itens por agentes também deve estar ativada.

Quando ativada, um salvamento verificado por meio de save_secret_item ou save_secret_from_clipboard aprova automaticamente todos os campos suportados do novo item no vault do agente configurado, incluindo CVV e PIN de cartão de crédito. O agente pode usar os identificadores criptografados resultantes imediatamente. Itens existentes e itens copiados ou movidos pelo console administrativo ainda precisam de aprovação manual.

onepassword-agent-mcp settings auto-approve on
onepassword-agent-mcp settings auto-approve off
onepassword-agent-mcp settings --json

Acesso sem Supervisão

O cartão Permissões → Acesso sem supervisão aceita um token de conta de serviço do 1Password diretamente no painel local. Crie o token nas configurações de conta de serviço do 1Password com acesso apenas ao seu vault de agente dedicado. Conceda read_items, além de write_items para salvamentos. No painel, cole-o em Token de conta de serviço e clique em Salvar token criptografado. A entrada é limpa imediatamente. Não envie o token no chat.

O aplicativo criptografa o token localmente em ~/.onepassword-mcp/access.json, nunca o retorna ao painel ou ao cliente MCP e o fornece apenas ao ambiente de processo da CLI. As alterações se aplicam a chamadas CLI posteriores sem reiniciar. Testar conexão verifica a visibilidade do vault; não grava um item de teste nem certifica permissões de gravação. Desative Usar conta de serviço salva para voltar à autenticação da área de trabalho, ou escolha Remover token salvo para excluir a credencial local. Revogue o token no 1Password se quiser invalidá-lo em todos os lugares. Operações em andamento podem terminar após uma alternância.

Um OP_SERVICE_ACCOUNT_TOKEN configurado externamente tem precedência; o painel relata esse modo, e remover um token local não pode desativar a credencial de ambiente. Contas de serviço não podem acessar vaults Pessoal/Privado/Funcionário integrados. Enquanto o acesso sem supervisão com escopo estiver ativo, o console só pode ver vaults que esse token pode acessar; desative-o antes de copiar itens de outros vaults da conta da área de trabalho.

Existem três camadas de permissão separadas:

Este aplicativo não altera as confirmações de ferramentas do seu cliente MCP nem contorna as proteções de desbloqueio da área de trabalho do 1Password. Consulte o modelo de segurança da integração de área de trabalho do 1Password e a documentação da CLI de conta de serviço.

Configuração do Cliente

A CLI de configuração imprime uma simulação por padrão. Ela detecta Claude Code, Claude Desktop, Codex, VS Code, agentes de codificação Xcode e Raycast AI quando instalados:

onepassword-agent-mcp setup all

Aplique a configuração a cada cliente detectado:

onepassword-agent-mcp setup all --apply

O comando usa caminhos absolutos do executável para que os aplicativos GUI não dependam do PATH do Terminal. O Claude Desktop e o JSON do VS Code são mesclados com backups com timestamp. As pastas de configuração privadas do Codex e do Claude do Xcode são tratadas separadamente porque o Xcode não usa a configuração normal da CLI.

O Raycast armazena a configuração do MCP no armazenamento gerenciado pelo aplicativo e não expõe um gravador de configuração externo suportado. A CLI abre a tela oficial Import Servers do Raycast; revise a entrada preparada e confirme-a uma vez no Raycast. Esta é a única etapa interativa específica do cliente.

Claude Code

onepassword-agent-mcp setup claude-code --apply

Comando equivalente:

claude mcp add --scope user onepassword-agent-mcp -- onepassword-agent-mcp mcp

Codex

onepassword-agent-mcp setup codex --apply

Comando equivalente:

codex mcp add onepassword-agent-mcp -- onepassword-agent-mcp mcp

GitHub Copilot No VS Code

onepassword-agent-mcp setup copilot --apply

Comando equivalente do VS Code:

code --add-mcp '{"name":"onepassword-agent-mcp","command":"onepassword-agent-mcp","args":["mcp"]}'

Fallback do espaço de trabalho em .vscode/mcp.json:

{
  "servers": {
    "onepassword-agent-mcp": {
      "type": "stdio",
      "command": "onepassword-agent-mcp",
      "args": ["mcp"]
    }
  }
}

Claude Desktop

onepassword-agent-mcp setup claude-desktop --apply

A CLI mescla com segurança o servidor no JSON do usuário do Claude Desktop e preserva todas as outras configurações.

Xcode

onepassword-agent-mcp setup xcode --apply

Isso configura os ambientes isolados do Codex e do Claude Agent usados apenas dentro do Xcode.

Raycast AI

onepassword-agent-mcp setup raycast --apply

O Raycast abre sua tela de importação nativa para a confirmação final. O Raycast pergunta antes das chamadas de ferramentas do MCP por padrão.

ChatGPT Desktop

O ChatGPT Desktop não é intencionalmente incluído na configuração local. O ChatGPT atualmente se conecta a servidores MCP remotos em vez de comandos stdio locais arbitrários. Não exponha esta ponte de senha através de um túnel público apenas para conectá-la.

Outros Clientes MCP

Imprimir JSON MCP genérico:

onepassword-agent-mcp setup generic --json

Configuração genérica:

{
  "mcpServers": {
    "onepassword-agent-mcp": {
      "command": "onepassword-agent-mcp",
      "args": ["mcp"]
    }
  }
}

Tempo De Execução E Barra De Menu

Instalar o pacote npm adiciona apenas comandos. Não instala um agente de inicialização, daemon, serviço em segundo plano, item de inicialização, extensão de navegador ou processo residente oculto.

• onepassword-agent-mcp admin executa o console de aprovação local apenas enquanto esse processo de terminal estiver ativo.
• onepassword-agent-mcp mcp é um servidor MCP stdio. Clientes MCP como Claude Code, Codex ou VS Code o iniciam como um processo filho quando precisam dele.
• onepassword-agent-mcp setup ... --apply apenas grava a configuração do cliente MCP. Os arquivos JSON existentes são copiados antes de uma mesclagem.
• O complemento opcional da barra de menu do macOS é instalado somente quando você o escolhe explicitamente. Seu ícone fica visível sempre que está em execução.
• Iniciar no login é uma escolha separada e está desativado por padrão. Mesmo quando ativado, o aplicativo visível da barra de menu não inicia o servidor admin até que você escolha Abrir Console Admin.
• Reiniciar o computador não inicia automaticamente este projeto, a menos que você tenha ativado o item de login opcional da barra de menu ou outro aplicativo inicie um cliente MCP que então inicie o servidor stdio.
• O estado local em ~/.onepassword-mcp inclui configurações, aprovações, dados de perfil, metadados de auditoria e operações de salvamento, a chave de criptografia, credenciais opcionais de conta de serviço criptografadas e registros de repetição da área de transferência. Consulte Estado Local.

Você pode ver esta explicação a qualquer momento:

onepassword-agent-mcp runtime

Barra De Menu Opcional Do Mac

No macOS, o instalador guiado pode adicionar um item 1P claramente rotulado à barra de menu. Você também pode ativá-lo mais tarde em Permissões → Atalho da Barra de Menu do Mac no painel.

O complemento é construído localmente a partir do código-fonte Swift legível em native/MenuBarApp.swift. Nenhum binário de aplicativo opaco é enviado no pacote npm. O aplicativo gerado usa o logotipo de escudo verde-azulado do projeto, é colocado em ~/Applications/1Password Agent MCP.app e nunca solicita acesso de administrador.

Controles manuais:

onepassword-agent-mcp menubar status
onepassword-agent-mcp menubar install
onepassword-agent-mcp menubar launch
onepassword-agent-mcp menubar remove
onepassword-agent-mcp menubar install --launch-at-login
onepassword-agent-mcp menubar login on
onepassword-agent-mcp menubar login off
onepassword-agent-mcp menubar uninstall --apply

Use menubar remove para fechar o atalho visível sem desinstalá-lo, e menubar launch para mostrá-lo novamente. Use menubar install após desinstalá-lo. A página admin local oferece os mesmos controles de instalação em Permissões → Atalho da Barra de Menu do Mac enquanto o console admin está em execução.

O menu contém Abrir Console Admin, Parar Console Admin, Iniciar Barra de Menu no Login, Remover da Barra de Menu e Desinstalar Atalho da Barra de Menu. Abrir Console Admin inicia o console quando necessário e depois o abre, então não há ação Separada de Iniciar. Remover da Barra de Menu apenas fecha o auxiliar visível; ele permanece instalado e pode ser reaberto. Desinstalar Atalho da Barra de Menu remove o auxiliar e seu item de login após a confirmação. Nenhuma das ações altera a configuração do cliente MCP, aprovações locais, MCPVAULT ou itens do 1Password.

O próprio console admin tem controles de processo explícitos:

onepassword-agent-mcp admin status
onepassword-agent-mcp admin stop

Ferramentas MCP

• onepassword_status: verifica CLI, MCPVAULT, aprovações locais, dados de perfil e configurações.
• find_secrets_for_site: retorna handles criptografados aprovados para um site.
• list_approved_secrets: lista handles aprovados e sites permitidos.
• copy_secret: resolve um handle e copia o campo selecionado para a área de transferência.
• paste_secret: resolve um handle, copia-o, cola no aplicativo ativo e não retorna texto simples.
• clear_secret_clipboard: limpa a área de transferência.
• save_secret_item: salva um novo login, senha, credencial de API, nota segura ou cartão de crédito em MCPVAULT quando a configuração de salvamento local está ativada. Retorna status de verificação e aprovação, além de approvedFields (e o primeiro campo como approvedField para compatibilidade). A aprovação automática segue a configuração local autoApproveAgentItems.
• save_secret_from_clipboard: salva texto copiado localmente exato com argumentos de ferramenta somente metadados, captura de repetição criptografada, verificação e aprovação automática opcional. Requer permissões de salvamento da área de transferência e criação de itens.
• get_profile_data: retorna dados de perfil definidos pelo usuário permitidos para o site atual.
• find_passwords_for_site, list_approved_passwords, copy_password, paste_password e clear_password_clipboard: aliases de compatibilidade.
• admin_ui_info: retorna a URL do console de aprovação.

Verificação De Salvamento E Repetições

save_secret_item relata created, verified, itemId, vaultId e operationId. O sucesso requer uma releitura que corresponda ao título pretendido, categoria, destino, sites e valores de campo. Os valores secretos são comparados localmente e nunca são incluídos no resultado. O opcional approvalStatus é separado: um item pode ser salvo e verificado enquanto sua aprovação ainda precisa de revisão na interface admin.

Reutilize o mesmo requestId e entrada após um salvamento interrompido. Se omitido, conteúdos de item idênticos no mesmo destino são deduplicados. Forneça um novo requestId apenas para criar intencionalmente outro item. A recuperação usa uma tag de item única opmcp-… e um registro de operação local, nunca uma correspondência de título. Se uma operação anterior não puder ser reconciliada, a ferramenta relata um resultado não resolvido em vez de criar silenciosamente outro item. Uma aprovação revogada pelo usuário nunca é restabelecida por uma repetição de salvamento.

No macOS e Linux, o JSON atravessa um pipe do SO sem arquivos temporários de texto simples ou valores secretos nos argumentos do comando. O executor preserva a sessão do terminal para autorização do 1Password e limpa seu grupo de processos filho em tempo limite ou cancelamento. A cópia lê e verifica campos JSON suportados, incluindo valores ocultos. Itens contendo anexos, documentos ou chaves de acesso devem ser copiados usando o aplicativo 1Password.

Reinicie os clientes MCP existentes e o console admin após a atualização para que cada gravador use o bloqueio de política atual e o código de verificação de salvamento. As configurações existentes, aprovações e a chave de criptografia são retidas.

Modelo De Segurança

Protegido:

• Os segredos dos itens salvos permanecem no 1Password. Os salvamentos da área de transferência usam capturas de repetição criptografadas temporárias; um token opcional de conta de serviço sem supervisão é criptografado localmente.
• As ferramentas de copiar/colar do MCP nunca retornam campos secretos de texto simples do 1Password.
• Handles e referências secretas armazenadas do 1Password são criptografados localmente.
• Aprovações desativadas ou excluídas invalidam handles antigos.
• As verificações de sites permitidos são executadas novamente no momento de copiar e colar.
• O servidor MCP apenas lista e resolve aprovações do vault de agente configurado.
• Itens criados por agentes e captura da área de transferência são opt-ins separados; novos itens são salvos apenas no vault de agente configurado.
• A aprovação automática de campos criados por agentes é uma configuração opt-in separada e fica desativada por padrão.

Ainda sensível:

• A área de transferência do SO contém brevemente o valor do campo em texto simples.
• O aplicativo ativo recebe o valor do campo quando a colagem é acionada.
• Um processo local com acesso à área de transferência pode observar segredos copiados.
• A chave de criptografia é local para a mesma conta de usuário. Um processo que pode ler tanto a chave quanto os arquivos criptografados pode descriptografá-los.
• Com a integração da CLI do desktop, a sessão local da CLI do 1Password pode ter acesso mais amplo ao vault do que o MCP expõe.
• get_profile_data retorna valores de perfil em texto simples que você adicionou explicitamente na interface admin.

Para o limite mais estrito, use uma conta de serviço do 1Password com escopo apenas para MCPVAULT.

Leia docs/SECURITY.md antes de usar isso com agentes poderosos de controle de navegador.

Estado Local

O diretório de estado padrão é ~/.onepassword-mcp:

Os segredos dos itens salvos vivem no 1Password. Capturas criptografadas e credenciais de conta de serviço são as exceções locais descritas acima. Isso é criptografia local, não proteção contra um processo que pode ler tanto o texto cifrado quanto a chave.

Use um diretório de estado diferente:

ONEPASSWORD_MCP_HOME=/path/to/state onepassword-agent-mcp admin

Use um nome de vault de agente diferente para uma nova configuração:

MCP_VAULT_NAME=AgentVault onepassword-agent-mcp admin

Para uma instalação existente, altere Permissões → Configurações locais avançadas → Nome do vault do agente e salve. Mantenha o console admin e os clientes MCP no mesmo diretório de estado.

Para implantações headless, forneça OP_SERVICE_ACCOUNT_TOKEN com segurança no ambiente do servidor MCP. Um token de ambiente tem precedência sobre o token salvo no painel. Não envie tokens para o controle de versão nem os cole em uma conversa de agente.

Parar E Desinstalar

Pare o console de aprovação local pressionando Ctrl-C no terminal que executa:

onepassword-agent-mcp admin

Desconecte os clientes MCP:

onepassword-agent-mcp uninstall all
onepassword-agent-mcp uninstall all --apply

O comando de desinstalação remove suas entradas do Claude Code, Claude Desktop, Codex, VS Code e Xcode onde presentes, e então remove o aplicativo/item de login opcional da barra de menu. O Raycast abre Gerenciar Servidores para uma remoção explícita porque suas configurações são gerenciadas pelo aplicativo. Outras configurações de cliente e todos os dados do 1Password permanecem intactos.

Opcional: exclua o estado local deste aplicativo, incluindo aprovações, dados de perfil, configurações, a chave de criptografia, token salvo da conta de serviço e registros de repetição da área de transferência:

onepassword-agent-mcp uninstall state
onepassword-agent-mcp uninstall state --apply

Isso exclui ~/.onepassword-mcp. Não exclui vaults ou itens do 1Password, nem revoga um token de conta de serviço no 1Password. Exclua MCPVAULT dentro do 1Password somente se você intencionalmente quiser remover esse vault.

Finalmente, remova o pacote npm global após qualquer limpeza opcional de estado:

npm uninstall -g onepassword-agent-mcp

Solução De Problemas

Execute onepassword-agent-mcp doctor para verificar a descoberta da CLI, autorização, visibilidade do vault, permissão de criação local e atividade do console.

Desenvolvimento

Clone e instale:

git clone https://github.com/gambadio/onepassword-agent-mcp.git
cd onepassword-agent-mcp
npm ci

Execute localmente com npm run dev:admin ou npm run dev:mcp.

Verificação

npm ci
npm run typecheck
npm test
npx playwright install chromium
npm run test:ui
npm run build
node scripts/test-live.mjs

O comando final testa todas as cinco categorias usando execuções simuladas reais da CLI. Desbloqueie o 1Password e autorize o acesso à CLI quando solicitado. Para testar adicionalmente salvamentos MCP reais, leitura exata, deduplicação de repetição e cópia, execute:

node scripts/test-live.mjs --create

Isso requer a configuração salva de criação de agente. Ele cria fixtures sintéticos exclusivamente marcados no cofre do agente configurado, verifica-os e, em seguida, move esses fixtures exatos para Excluídos Recentemente. Ele usa estado de política local isolado. Se a verificação ou limpeza falhar, ele imprime o diretório de estado de recuperação e o retém para inspeção. doctor verifica a autorização da CLI, visibilidade do destino, permissão de criação local e atividade do console; ele não realiza validação de salvamento/cópia.

As versões do mantenedor são automatizadas por meio do GitHub Actions com credenciais OIDC de curta duração. Consulte docs/RELEASING.md; npm publish local e autorização repetida de dispositivo não fazem parte do processo de versão.

Licença

MIT