secret-vault-mcp: um cofre de senhas para seus agentes de IA

Agentes de IA precisam acessar serviços — GitHub, AWS, bancos, APIs. Até agora, o padrão era jogar a senha no prompt ou manter num .env dentro do projeto. O secret-vault-mcp resolve isso: um vault criptografado local que o LLM consulta via MCP, sem nunca expor a senha mestra.

Criptografia de verdade

Nada de obfuscation ou "security through obscurity":

• AES-256-GCM com nonce aleatório de 12 bytes por operação
• PBKDF2-HMAC-SHA256 com 600.000 iterações (recomendação OWASP)
• Sal aleatório de 16 bytes por vault
• Master password jamais escrita em disco, jamais logada, jamais transmitida

O vault vive em disco como ciphertext em ~/.local/share/secret-vault-mcp/, protegido por flock para acesso concorrente e escrita atômica com temp file

• os.replace.

8 ferramentas MCP

O LLM ganha acesso completo ao vault via ferramentas tipadas:

| Ferramenta | O que faz | |------------|-----------| | add_secret | Adiciona entrada (name, username, password, url?, notes?) | | get_secret | Consulta entrada; reveal_password=true expõe a senha | | list_secrets | Lista todas as entradas sem senhas | | update_secret | Atualiza campos específicos | | delete_secret | Remove entrada | | generate_password | Gera senha forte (20+ chars, configurável) | | search_secrets | Busca textual em nome/url/username/notes | | vault_status | Metadados: total de entradas, último acesso, versão |

O design é intencional: list_secrets sempre retorna password="". Só get_secret com reveal_password=true expõe a senha — e o LLM só faz isso quando você pede explicitamente.

Exemplo no dia a dia

> store these credentials: github/felipe/<gen-32>, aws-root/admin/<gen-40>
> list all entries
> get the aws-root entry and reveal the password
> generate a 32-character password, then update the github entry with it
> delete entries named "test-1"

Tudo via linguagem natural. O cliente MCP traduz para tools/call por baixo dos panos.

Testes e cobertura

pytest                    # 47 testes
pytest --cov=server       # ~87% de cobertura

CI/CD com GitHub Actions: ruff + pytest em todo push, release automática no main.

Registro no OpenCode

Adicione ao ~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "secret-vault": {
      "type": "stdio",
      "command": "/home/felipe/infra/secret-vault-mcp/.venv/bin/python3",
      "args": ["-u", "/home/felipe/infra/secret-vault-mcp/server.py"],
      "env": {
        "VAULT_MASTER_PASSWORD": "sua-frase-secreta-aqui"
      },
      "enabled": true
    }
  }
}

A senha mestra deve vir de um cofre de verdade (1Password CLI, pass, system keyring) — nunca versionada.

O código completo está no repositório: github.com/n8nfelipe/secret-vault-mcp.