Generate and verify TOTP/HOTP one-time passwords (RFC 6238/4226) and build otpauth:// URIs for authenticator apps via @mukundakatta/otp-mcp

@mukundakatta/otp-mcp v0.1.0 — TOTP/HOTP one-time passwords + otpauth URI builder

Install: npm install @mukundakatta/otp-mcp @modelcontextprotocol/sdk Entry: dist/server.js (stdio) 3 tools: totp, hotp, uri

Tool schemas

• totp({secret, period?, digits?, algorithm?, at?}) → {code, counter, period} — RFC 6238 time-based OTP. Secret is base32. at is optional Unix ms timestamp (defaults to now).
• hotp({secret, counter, digits?, algorithm?}) → {code} — RFC 4226 counter-based OTP.
• uri({type?, secret, label, issuer?, period?, counter?, digits?, algorithm?}) → {uri} — builds otpauth:// URI for QR codes (Google Authenticator, Authy, etc).

Key observations

• Deterministic: same secret + same counter/timestamp = same code (verified)
• 3 algorithms: SHA1 (default), SHA256, SHA512 — all tested working
• Configurable digits: 4-10 (default 6); 8-digit codes tested
• Custom period: default 30s, tested with 60s (different counter = different code)
• TOTP returns counter: counter = floor(unixMs / (period * 1000)) — useful for debugging time windows
• URI builder: properly URL-encodes labels, includes issuer prefix, encodes algorithm/digits/period
• HOTP counter: caller-supplied, minimum 0
• Sub-millisecond after JIT: first call ~13ms, rest 0-3ms

Gotchas

• Secret must be base32-encoded — raw ASCII/hex will produce wrong codes
• TOTP `at` param is milliseconds (not seconds) — pass Date.now() or unixSeconds * 1000
• No `verify` tool — you generate the code and compare client-side
• No secret generator — you must supply your own base32 secret
• URI `label` format is issuer:account — the tool prefixes issuer automatically when both are given

Sample HOTP trace

hotp({secret: "JBSWY3DPEHPK3PXP", counter: 0}) => {code: "282760"}
hotp({secret: "JBSWY3DPEHPK3PXP", counter: 1}) => {code: "996554"}
hotp({secret: "JBSWY3DPEHPK3PXP", counter: 0}) => {code: "282760"} // deterministic
hotp({secret: "JBSWY3DPEHPK3PXP", counter: 5, digits: 8}) => {code: "38768897"}
hotp({secret: "JBSWY3DPEHPK3PXP", counter: 0, algorithm: "SHA256"}) => {code: "023015"}
hotp({secret: "JBSWY3DPEHPK3PXP", counter: 0, algorithm: "SHA512"}) => {code: "582788"}

Sample TOTP trace (fixed timestamp for reproducibility)

totp({secret: "JBSWY3DPEHPK3PXP", at: 1704067200000}) => {code: "432690", counter: 56802240, period: 30}
totp({secret: "JBSWY3DPEHPK3PXP", at: 1704067200000, digits: 8}) => {code: "76432690", counter: 56802240, period: 30}
totp({secret: "JBSWY3DPEHPK3PXP", at: 1704067200000, algorithm: "SHA256"}) => {code: "879973", counter: 56802240, period: 30}
totp({secret: "JBSWY3DPEHPK3PXP", at: 1704067200000, period: 60}) => {code: "039666", counter: 28401120, period: 60}

Sample URI trace

uri({secret: "JBSWY3DPEHPK3PXP", label: "[email protected]", issuer: "MyApp"}) => {uri: "otpauth://totp/MyApp:alice%40example.com?issuer=MyApp&secret=JBSWY3DPEHPK3PXP&algorithm=SHA1&digits=6&period=30"}
uri({type: "hotp", secret: "JBSWY3DPEHPK3PXP", label: "[email protected]", issuer: "TestCo", counter: 42}) => {uri: "otpauth://hotp/TestCo:bob%40example.com?issuer=TestCo&secret=JBSWY3DPEHPK3PXP&algorithm=SHA1&digits=6&counter=42"}
uri({type: "totp", secret: "JBSWY3DPEHPK3PXP", label: "[email protected]", issuer: "Corp", digits: 8, algorithm: "SHA256", period: 60}) => {uri: "otpauth://totp/Corp:admin%40corp.io?issuer=Corp&secret=JBSWY3DPEHPK3PXP&algorithm=SHA256&digits=8&period=60"}