MCP 服务器

auth-vault

MCP server for secure credential management, browser-based login automation, and TOTP/2FA auto-solving. Encrypts credentials with AES-256-GCM and automates login flows via Playwright.

README

@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).

Interface	Port	URL
Web UI Dashboard	`5500`	`http://<tailscale-ip>:5500/`
MCP SSE	`5501`	`http://<tailscale-ip>:5501/sse`
MCP Health	`5501`	`http://<tailscale-ip>:5501/health`

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:

Variable	Default	Description
`VAULT_ROOT`	`./vault`	Storage directory for encrypted vault files
`VAULT_ENCRYPTION_KEY`	`auto-generated`	AES-256 key (64 hex chars, persist for data survival)
`AUTH_SSE_PORT`	—	Enable SSE mode on given port (empty = STDIO mode)
`AUTH_BIND_ADDRESS`	auto (Tailscale)	Explicit bind address for SSE mode
`BROWSER_HEADLESS`	`true`	Run Playwright in headless mode
`BROWSER_TIMEOUT`	`30000`	Browser operation timeout (ms)
`LOG_LEVEL`	`info`	Logging level: debug, info, warn, error

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