@mcp/auth-vault

🧩 Branch template — czysta wersja do klonowania i adaptacji.
Brak testów specyficznych dla Q-ekosystemu, brak danych wrażliwych.
Własne serwisy konfigurujesz przez add_service — wystarczą selektory CSS.

MCP server for secure credential management, browser-based login automation, and TOTP/2FA auto-solving.

Status:  active    |    License: MIT    |    Version: 0.1.0

Overview

Auth Vault stores encrypted credentials and secrets (AES-256-GCM), automates browser login flows via Playwright, and auto-solves TOTP-based 2FA challenges. It provides both an MCP interface (for AI clients) and a Web UI dashboard (for manual management).

Related MCP server: playwright-sse-mcp-server

Features

• Encrypted vault — credentials and secrets stored with AES-256-GCM

• Browser automation — Playwright-based login with form filling

• TOTP/2FA auto-solve — RFC 6238 implementation, generates and submits 2FA codes

• QR code support — generate QR for Google Authenticator setup

• Secrets management — API keys, bearer tokens, access/refresh tokens

• Tailscale-only access — binds to Tailscale IP by default, blocks external traffic

• Two service modes — STDIO (MCP standard) and SSE (HTTP for persistent connections)

Quick Start

Prerequisites

• Node.js 22+

• Playwright Chromium (installed via postinstall)

• Tailscale (recommended for SSE mode)

Setup

# Install dependencies
npm install

# Build TypeScript
npm run build

# Configure environment
cp .env.example .env
# Edit .env: set VAULT_ENCRYPTION_KEY (64 hex chars) or leave empty for auto-generated

Configuration

All configuration via .env file or environment variables:

Usage

STDIO Mode (default for MCP clients)

node dist/index.js

SSE Mode (HTTP server for persistent connections)

# Set AUTH_SSE_PORT=5501 in .env, then:
node dist/index.js

Web UI Dashboard

node dist/web/server.js
# Dashboard at http://<tailscale-ip>:5500/

CLI Commands

npm run add-creds     # Add credentials interactively
npm run add-secret    # Add a secret interactively
npm run list-creds    # List stored credentials
npm run list-secrets  # List stored secrets
npm run get-creds     # Get credential details

Systemd Services

# MCP SSE server (port 5501)
systemctl status mcp-auth-vault

# Web UI dashboard (port 5500)
systemctl status mcp-auth-vault-web

Both services restart automatically on failure and enable at boot.

Security

• AES-256-GCM encryption for all stored credentials and secrets

• Tailscope-restricted — SSE mode blocks non-Tailscale connections

• Encryption key persisted in .env — if lost, data cannot be recovered

• Headless browser — no visible UI during automated logins

Project Structure

src/
├── index.ts              # MCP server entry (STDIO + SSE)
├── config.ts             # Zod-validated configuration
├── credentials/
│   ├── totp.ts           # TOTP (RFC 6238) implementation
│   ├── qr.ts             # QR code generation + TOTP secret generator
│   ├── vault.ts          # Encrypted credential store
│   └── types.ts          # Credential type definitions
├── secrets/
│   ├── manager.ts        # Encrypted secrets store
│   └── types.ts          # Secret type definitions
├── browser/
│   └── manager.ts        # Playwright session management
├── services/
│   └── definitions.ts    # Login templates (Google, etc.)
├── web/
│   ├── server.ts         # Web UI HTTP server + REST API
│   └── dashboard.ts      # HTML dashboard template
├── tools/
│   ├── credentials.ts    # MCP tool definitions for credentials
│   ├── secrets.ts        # MCP tool definitions for secrets
│   ├── services.ts       # MCP tool definitions for services
│   └── login.ts          # MCP tool definitions for login
└── cli/
    ├── add-credentials.ts
    └── add-secret.ts

Tech Stack

• Runtime: Node.js 24, TypeScript ESM

• MCP: @modelcontextprotocol/sdk v1.16

• Encryption: Node.js crypto (AES-256-GCM)

• Browser: Playwright (Chromium)

• Config: Zod validation

• UI: Vanilla JS (no framework)

• QR: qrcode npm package

License

MIT