TOTP MCP Server

MCP server for generating TOTP (Time-based One-Time Password) 2FA codes for Claude Code automation.

Features

• Generate 6-digit TOTP codes for configured accounts

• Codes are valid for ~30 seconds (standard TOTP)

• Shows remaining validity time

• Reads secrets from external file (not hardcoded)

Installation

cd ~/.claude/mcp-servers/totp
npm install

Configuration

1. Create a secrets file (e.g., ~/.nutrie-secrets):

   GOOGLE_TOTP_SECRET=JBSWY3DPEHPK3PXP

2. Update SECRETS_FILE path in index.js if needed

3. Add accounts to the ACCOUNTS object in index.js:

   const ACCOUNTS = {
     "google": "GOOGLE_TOTP_SECRET",
     "github": "GITHUB_TOTP_SECRET",
   };

MCP Configuration

Add to your .mcp.json:

{
  "mcpServers": {
    "totp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/.claude/mcp-servers/totp/index.js"]
    }
  }
}

Tools

get_totp_code

Generate a TOTP code for an account.

Parameters:

• account (required): Account name (e.g., "google")

Example:

TOTP code for google: 123456
Valid for 24 more seconds

list_totp_accounts

List all configured TOTP accounts and their status.

Security

• TOTP secrets are stored in an external file, not in the code

• The secrets file should have restricted permissions (chmod 600)

• Never commit secrets to git

Troubleshooting

TOTP code is rejected / invalid

TOTP codes are time-sensitive. The most common cause of invalid codes is clock drift.

• Check system time: date — ensure it's accurate to within a few seconds

• Sync time (Linux): sudo timedatectl set-ntp true

• Sync time (macOS): System Settings → General → Date & Time → Set automatically

"Account not found" error

The account name must exactly match a key in the ACCOUNTS object in index.js.

• Run list_totp_accounts to see all configured account names

• Account names are case-sensitive (google ≠ Google)

Secrets file not found

• Verify the SECRETS_FILE path in index.js points to your actual secrets file

• Confirm the file exists: ls -la ~/.nutrie-secrets (or your configured path)

• Check file permissions allow reading: chmod 600 ~/.nutrie-secrets

MCP server fails to start

• Run npm install in the totp directory to ensure dependencies are installed

• Test manually: node index.js — any startup errors will print to stderr

• Verify the path in .mcp.json is absolute and correct

TOTP secret is wrong / codes always fail

• Re-scan or re-copy the TOTP secret from your account's 2FA setup page

• Secrets are base32-encoded — ensure no extra spaces or line breaks in the secrets file

• Confirm the correct environment variable name is mapped in ACCOUNTS

License

MIT