Repository avatar
AI Tools
v1.0.0
active

mcp

com.base64hub/mcp

Exact Base64 for AI agents: encode, decode and validate (standard, URL-safe, data URIs).

Documentation

base64hub-mcp

An MCP server that gives AI assistants exact Base64: encode, decode and validate. Language models are unreliable at Base64 by hand; with this server Claude, Cursor, VS Code and any other Model Context Protocol client get byte-exact results from three small tools.

  • Runs locally over stdio, nothing leaves your machine, no network access, no API key
  • Zero dependencies, a few hundred lines of plain Node.js (18 or newer)
  • Standard and URL-safe alphabets, padding control, line wrapping, data URIs
  • Lenient decoding with precise errors: invalid character '!' at position 4
  • Binary results are reported as hex instead of mangled text

Setup

The server is started by your MCP client with npx -y base64hub-mcp. Node.js 18 or newer must be installed.

Claude Code

claude mcp add base64hub -- npx -y base64hub-mcp

Add --scope user to make it available in every project.

Claude Desktop

Open Settings → Developer → Edit Config and add the server to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\), then restart Claude:

{
  "mcpServers": {
    "base64hub": {
      "command": "npx",
      "args": ["-y", "base64hub-mcp"]
    }
  }
}

Cursor

Add it to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "base64hub": {
      "command": "npx",
      "args": ["-y", "base64hub-mcp"]
    }
  }
}

VS Code

From a terminal:

code --add-mcp '{"name":"base64hub","type":"stdio","command":"npx","args":["-y","base64hub-mcp"]}'

Or in a workspace file. .vscode/mcp.json uses a top-level servers object:

{
  "servers": {
    "base64hub": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "base64hub-mcp"]
    }
  }
}

The portable .mcp.json at the workspace root (also read by Copilot) uses mcpServers with the same command and args as the Cursor example.

Other clients

Any client that launches stdio servers works with command npx and arguments -y base64hub-mcp. On Windows, if a client can't find npx, use command cmd with arguments /c npx -y base64hub-mcp.

Tools

All tools are read-only and work offline.

base64_encode

Encode text (as UTF-8) to Base64.

ArgumentTypeDefaultMeaning
textstringrequiredText to encode
url_safebooleanfalseURL-safe alphabet (- and _, RFC 4648 §5)
paddingbooleantrueAdd = padding
wrapinteger0Line break after every N characters (76 = MIME)

{"text": "Hello, hub!"} → SGVsbG8sIGh1YiE=

base64_decode

Decode Base64 to text. Accepts both alphabets (even mixed), missing padding, spaces, tabs and line breaks, and data:...;base64, URIs.

ArgumentTypeMeaning
datastringBase64 text or a data URI

{"data": "SGVsbG8sIGh1YiE"} → Hello, hub!

When the bytes are not valid UTF-8 (an image, for example), the result says so and gives them as hex. Invalid input returns a tool error with the reason, such as Invalid Base64: invalid character '!' at position 4.

base64_validate

Check a string without decoding it. Returns JSON, also as structured content:

FieldMeaning
validtrue exactly when base64_decode would succeed
variantstandard (+ or / seen), url (- or _ seen), mixed (both) or either (neither)
paddedthe length including = is a multiple of 4
bytesdecoded size in bytes
errorthe error base64_decode would report (only when valid is false)

{"data": "a+b_"} → {"valid":true,"variant":"mixed","padded":true,"bytes":3}

Protocol

JSON-RPC 2.0 over stdio, one message per line, written without an SDK. Supported MCP revisions: 2026-07-28 (stateless requests with per-request _meta and server/discover) and, through the initialize handshake, 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05. Logs go to stderr only.

Links

License

MIT

NPM
base64hub-mcp
Install Command
npm install base64hub-mcp
Runtime: npx