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)

Field	Notes
mode	crystal | crystal-video | clarity | creative | clarity-pro
image	Public image URL or local file (all image modes)
video	Public video URL or local file (crystal-video)
publish	uguu (default) | litterbox | funnel | none — how to expose a local file as raw bytes
webhook	Optional. Result is POSTed here instead of returned
output_path	Optional local file or directory to save the result
include_raw_response	Optional debug flag

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

Name	Default	Purpose
CLARITY_API_KEY	—	Required (or CAI_API_KEY)
CLARITY_BASE_URL	https://api-upscale.clarityai.co	Override the endpoint
CLARITY_TIMEOUT	300000	curl timeout in ms
CLARITY_OUTPUT_DIR	—	Auto-save results when output_path is omitted
CLARITY_PUBLISH	uguu	Default publisher for local files
CLARITY_LITTERBOX_TIME	1h	litterbox TTL (1h / 12h / 24h / 72h)

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