clarity-api-mcp

Bun MCP server for the Clarity AI upscaler. One POST endpoint, every official mode.

Features

• Tools: clarity_list_models, clarity_upscale

• Modes: crystal, crystal-video, clarity (creative alias), clarity-pro

• Local files: published to a raw public URL (uguu, litterbox, or Tailscale Funnel) before the Clarity POST

• Dropbox share pages and tmpfiles.org HTML pages are rewritten to direct file URLs

• Bun-native: TypeScript with no compile step, automatic .env, Bun.file / Bun.write, Bun Shell curl

• Structured MCP output plus a text fallback

Requirements

• Bun >= 1.1

• A Clarity AI API key from https://clarityai.co/api

Setup

git clone https://github.com/thomastraum/clarity-api-mcp.git
cd clarity-api-mcp
bun install
cp .env.example .env

Put your key in .env (never commit this file):

CLARITY_API_KEY=your-key-here

Bun loads .env automatically. The server also reads this package's .env when a coding agent starts it from another directory.

MCP client config

Replace the path with your clone:

{
  "mcpServers": {
    "clarity-api": {
      "command": "bun",
      "args": ["/absolute/path/to/clarity-api-mcp/src/index.ts"]
    }
  }
}

The key can live in .env or in the MCP env block. See docs/INSTALL.md for Claude, Cursor, Codex, and Grok snippets.

Tools

clarity_list_models

Returns every mode, parameter list, and example body from the official API page.

clarity_upscale

Sends POST https://api-upscale.clarityai.co with Authorization: Bearer ….

Input (common)

Crystal — scale_factor 1–200, creativity 0–10, output_format jpg/png, target_megapixels 0.001–1500

Crystal Video — scale_factor 1–200

Clarity — creativity / resemblance / dynamic / fractality −10–10, scale_factor 2–16, style default/portrait/anime, postprocessing none/sharpen, prompt

Clarity Pro — creativity −10–10, scale_factor 2/4/8/16, output_format png/jpg. $0.03 per output MP, max 64 MP.

Output

{
  "mode": "crystal",
  "requested_mode": "crystal",
  "url": "https://…",
  "credit_cost": 3,
  "cost_usd": 0.03,
  "balance": 97,
  "webhook": null,
  "saved_to": "/path/to/out.jpg",
  "published_url": "https://a.uguu.se/…",
  "published_via": "uguu",
  "note": null
}

Clarity charges 1 credit = $0.01. Local files are published first so Clarity can fetch raw bytes. Use publish: "funnel" if the file should stay on this machine (Tailscale Funnel, not Serve).

Environment variables

Scripts

bun start
bun test
bun run smoke-test
bun run smoke-test -- --live

--live calls the real API and spends credits.

Notes

• Do not write to stdout from this process except the MCP transport. Diagnostics go to stderr.

• The HTTP client is Bun Shell curl, matching the official examples, with a Response body as stdin.

License

MIT