@clean-tools/mcp

A tiny stdio bridge to the Clean.tools remote MCP server.

Clean.tools runs an authless remote MCP server (Streamable HTTP) that exposes a set of read-only, deterministic developer, finance, and date/time utilities: cron parsing, RRULE expansion, timezone and strftime formatting, loan amortization, TVM, compound interest, APR, hashing, UUIDs, JWT decoding, regex testing, data-format conversion, unit conversion, QR encoding, and more. These are the same engines that power the site's tools, so a model can compute exact answers instead of guessing.

Most desktop MCP clients (Claude Desktop, Cursor, Windsurf, etc.) launch MCP servers as local subprocesses and talk to them over stdio. This package is a zero-dependency shim that speaks stdio to your client and proxies every JSON-RPC message to the remote HTTP endpoint.

• Zero dependencies. Pure Node built-ins (fetch, readline). Requires Node.js 18+.
• Nothing to trust it with. The server is authless and every tool is read-only, so there are no credentials and no writes.
• Configurable endpoint via an environment variable.

Usage

You do not need to install anything. Point your MCP client at npx:

{
  "mcpServers": {
    "clean-tools": {
      "command": "npx",
      "args": ["-y", "@clean-tools/mcp"]
    }
  }
}

• Claude Desktop: add the block above to claude_desktop_config.json (Settings -> Developer -> Edit Config), then restart Claude Desktop.
• Cursor / Windsurf / other clients: add the same block to that client's MCP config file (~/.cursor/mcp.json for Cursor).

Pointing at a different endpoint

By default the shim proxies to https://mcp.clean.tools/mcp. Override it with an environment variable, for example to target a local wrangler dev instance:

{
  "mcpServers": {
    "clean-tools": {
      "command": "npx",
      "args": ["-y", "@clean-tools/mcp"],
      "env": {
        "CLEAN_TOOLS_MCP_URL": "http://127.0.0.1:8787/mcp"
      }
    }
  }
}

MCP_REMOTE_URL is accepted as an alias for CLEAN_TOOLS_MCP_URL.

Global install (optional)

npm install -g @clean-tools/mcp
clean-tools-mcp   # reads JSON-RPC on stdin, writes JSON-RPC on stdout

How it works

The shim reads newline-delimited JSON-RPC 2.0 messages from stdin, POSTs each one to the configured Streamable-HTTP MCP endpoint (advertising both application/json and text/event-stream in Accept), and writes the resulting JSON-RPC message(s) back to stdout. It tracks the Mcp-Session-Id header and the protocol version negotiated during initialize so the remote session stays coherent. Notifications (messages without an id) that the server answers with 202 No Content produce no stdout, as required by the protocol. If the remote is unreachable, the shim returns a JSON-RPC error for the pending request rather than hanging.

Diagnostics are written to stderr; stdout carries only protocol traffic.

Talking to the server directly

If your client supports remote/HTTP MCP servers natively, you can skip this shim entirely and connect straight to:

https://mcp.clean.tools/mcp

There is also a plain REST API for non-MCP callers:

GET  https://mcp.clean.tools/api/tools          # list tools
POST https://mcp.clean.tools/api/tools/:name    # run a tool with a JSON body

License

MIT