atom-mcp

An MCP server, built with mcp-use, that exposes Atom as a ground tool. Give it a screenshot and a short instruction ("click the Save button") and it returns one click point. ground also renders an MCP Apps view: the screenshot with a marker on the predicted point.

Atom is a visual grounding model derived from TinyClick. It is 169 MB and runs on Apple silicon. It scores 75.9% on ScreenSpot v2 (966/1,272); that number is author-reported and not on a public leaderboard.

Status: Atom's runtime is not public yet

This server is plain Node and does no inference itself. It forwards each call to an Atom API at ATOM_URL. That API (Atom's inference server and model) is not public yet, and it only runs on Apple silicon, so there is no hosted version of this server.

Without the API, ground and atom_health return isError: true with Atom is not reachable at …. To see the MCP side work, run npm test: it builds the server and drives it over HTTP against a protocol stub that returns a fixed point. The stub checks the wiring, the view resource, and the error paths. It says nothing about Atom's accuracy.

This version has not been run against the real Atom runtime. The tests and the Atom API contract section below come from a stub, not from Atom. The view is not covered by automated tests.

Related MCP server: vision-mcp

Run

Requires Node 22.22.2 or later (engines in package.json).

npm install
npm test                         # build, then test against the protocol stub
npm run build && npm start       # http://localhost:3000/mcp
npm start -- --with-inspector    # same, plus the Inspector at /mcp/inspector
npm run dev                      # dev server, Inspector at /mcp/inspector

Settings: ATOM_URL (default http://127.0.0.1:8760), ATOM_TIMEOUT_MS (default 180000, because the first call loads the model), PORT.

Connect a client: claude mcp add --transport http atom http://localhost:3000/mcp. Shell smoke test (needs python3): bash scripts/smoke.sh /abs/path/shot.png "click the Save button".

Tools

• ground: instruction plus exactly one of image_path (absolute path) or image_base64 (bare or data URL). PNG, JPEG, or WebP. Returns the point in 0-1000 normalized and pixel coordinates. The server only sniffs the file signature (the first few bytes), so a truncated or corrupt file can still pass.

• atom_health: returns the Atom API's /health response.

Failures (Atom down, timeout, abstain, bad input, unexpected response) come back as isError: true with a one-line reason.

Atom API contract

What this server sends and accepts:

• GET /health returns {"ok": true, "result": {...}}.

• POST /ground with {"instruction": "...", "image_base64": "..."} returns {"ok": true, "result": {"action": "click", "normalized": {"x", "y"}, "pixel": {"x", "y"}, "image": {"width", "height"}, "duration_ms"}}. Any other action is an abstain, with an optional reason.

• Errors return {"ok": false, "error": "..."}.

Notes

The screenshot reaches the view through the result's _meta, so it stays out of the model's context. The Atom API has no auth; keep it on loopback.