Fitter

Fitter — web data for AI agents

Fitter turns any website or API into structured JSON — declaratively. One JSON/YAML config describes where the data lives (HTTP request, headless browser, file, static value) and what to extract (JSON paths, CSS selectors, XPath). No code, no brittle scraping scripts.

🚀 [Try it in your browser](https://pxyup.github.io/fitter/) — the real engine compiled to WebAssembly: live examples, a visual config builder, no install.

Because configs are plain data, LLMs can author them. The built-in MCP server lets Claude Code, Claude Desktop, or any MCP client write and run scraping pipelines on your machine, on demand:

*"Get the top 5 HackerNews stories with titles and scores"* → the model authors a fitter config, validates it, runs it locally, and gets clean JSON back.

One engine, five ways to use it:

Why fitter for AI agents?

• Declarative & auditable — the agent produces a config you can read, save and re-run, not throwaway code
• Local-first — all fetching happens on your machine; no third-party scraping API, no keys, no per-request billing
• Batteries included — HTTP client, headless browser (Playwright/Chromium/Docker), JSON/HTML/XML/XPath/PDF parsing, pagination, cached references, host rate-limits — in a single static binary
• Reusable — what the agent authored today becomes tomorrow's cron job or service config

How to use Fitter_MCP

Fitter MCP is a Model Context Protocol server (stdio transport) which lets any MCP client — Claude Code, Claude Desktop, IDE assistants, custom agents — run Fitter configs and get structured JSON back.

Quick start (Claude Desktop — one click)

Download fitter-mcp- - .mcpb from the release page and open it — Claude Desktop installs the server automatically.

Quick start (Claude Code)

# 1. get the binary: download fitter_mcp_<version>-<os>-<arch> from the release page

https://github.com/PxyUp/fitter/releases — or build it from source:

go build -o fitter_mcp ./cmd/mcp

2. register it once, available in every project

claude mcp add fitter -s user -- "$(pwd)/fitter_mcp"

Then just ask:

*Get the top 5 HackerNews stories with titles and scores using fitter*

The model calls fitter_config_reference, authors a config, optionally checks it with fitter_validate_config and executes it via fitter_run — all data fetching happens locally on your machine. For a ready-made pipeline try examples/config_morning_briefing.json:

*Run examples/config_morning_briefing.json with fitter and give me the briefing*

Register in Claude Desktop

{

"mcpServers": { "fitter": { "command": "/path/to/fitter_mcp" } } }

Browser support (Playwright)

The .mcpb bundle and native binary ship without browsers: HTTP, static and file connectors work out of the box, but browser configs (the playwright connector) need Playwright's browsers. A few ways to get them:

• On first use (native binary / `.mcpb`): set "install": true in the playwright connector — fitter downloads the driver + browser matching its built-in playwright-go version on first use (one-time, cached), so no separate install step is needed.
• Ahead of time (native, optional): to avoid the first-run download, install the browsers beforehand with the same playwright-go version fitter is built against (check go.mod, currently v0.6100.0):

  go run github.com/mxschmitt/playwright-go/cmd/playwright@v0.6100.0 install

Linux: append --with-deps to also install the required OS libraries

  The version must match `go.mod` exactly — `playwright-go` refuses to run against a mismatched driver. Then run configs without `"install": true`.

• Docker: use the ghcr.io/pxyup/fitter-mcp:playwright image, which bundles Chromium, Firefox and WebKit preinstalled (no "install": true needed).

Tools

The reference is also exposed as MCP resource fitter://config-reference for clients that support resources.

The config format is exactly the same as for Fitter_CLI: a top-level object with item (required), limits and references. Notifiers work too (the result is additionally pushed to http/telegram/redis/file/console); trigger_config and http_server are service-mode only and are ignored in MCP calls.

Remote / hosted mode (streamable HTTP)

By default fitter_mcp talks stdio. Pass --http to serve the streamable HTTP transport instead — for a shared team server, a container, or any remote deployment:

# serve MCP at http://<host>:8080/mcp (health probe at /healthz)

FITTER_MCP_AUTH_TOKEN=my-secret fitter_mcp --http :8080

register the remote endpoint in Claude Code

claude mcp add --transport http fitter http://localhost:8080/mcp --header "Authorization: Bearer my-secret"

• --http (env FITTER_MCP_HTTP_ADDR) — listen address; stdio mode when empty
• FITTER_MCP_AUTH_TOKEN — when set, every /mcp request must send Authorization: Bearer ; without it the endpoint is unauthenticated, so bind to localhost or put it behind a proxy
• --stateless (env FITTER_MCP_STATELESS=true) — no per-session state, so replicas can sit behind a load balancer without sticky sessions
• --metrics-addr (env FITTER_MCP_METRICS_ADDR) — serve Prometheus metrics on a separate address (e.g. 127.0.0.1:9091); works in stdio mode too; empty disables. Exposes MCP request counts by method, tool call durations by tool and outcome, and outbound HTTP request durations by host, method and status. The endpoint is unauthenticated — bind it to localhost or a private interface

The server shuts down gracefully on SIGINT/SIGTERM.

Docker

A slim multi-arch image (linux/amd64 + linux/arm64) ships with every release:

# hosted HTTP mode

docker run --rm -p 8080:8080 \ -e FITTER_MCP_HTTP_ADDR=:8080 \ -e FITTER_MCP_AUTH_TOKEN=my-secret \ ghcr.io/pxyup/fitter-mcp:latest

or stdio mode, spawned by the MCP client

claude mcp add fitter -s user -- docker run --rm -i ghcr.io/pxyup/fitter-mcp:latest

The slim image contains only the fitter binary and CA certificates: server/static/file connectors work, browser connectors (chromium/docker/playwright) do not.

For browser-based configs use the playwright variant, which bundles Playwright with Chromium, Firefox and WebKit (matched to the playwright-go version fitter is built against, so no "install": true is needed in configs):

docker run --rm -i ghcr.io/pxyup/fitter-mcp:playwright        # stdio mode

per-release tag: ghcr.io/pxyup/fitter-mcp:vX.Y.Z-playwright

It is built from Dockerfile.mcp-playwright; build with --build-arg PLAYWRIGHT_BROWSERS=chromium for a smaller Chromium-only image.

OAuth2 accounts in Docker

Both images ship fitter_cli, so the one-time OAuth2 login can run inside the container. Store the token on a volume mounted at /tokens (pre-created writable in the image) and share it with the MCP server:

# one-time login, device flow: no ports needed — open the printed url on any device

docker run --rm -it -v fitter-tokens:/tokens --entrypoint fitter_cli \ ghcr.io/pxyup/fitter-mcp:latest \ auth --provider github --client-id --client-secret --token-file /tokens/github.json

or browser flow (device flow not enabled for the app): publish the callback port and

bind on 0.0.0.0 so the published port reaches the listener; the browser still visits 127.0.0.1

docker run --rm -it -p 8988:8988 -e FITTER_AUTH_LISTEN=0.0.0.0 \ -v fitter-tokens:/tokens --entrypoint fitter_cli ghcr.io/pxyup/fitter-mcp:latest \ auth --provider github --client-id --client-secret --token-file /tokens/github.json

then run the MCP server with the same volume; configs reference "token_file": "/tokens/github.json"

stdio mode (spawned by the MCP client, no port):

docker run --rm -i -v fitter-tokens:/tokens ghcr.io/pxyup/fitter-mcp:latest

hosted HTTP mode (MCP endpoint on 8080, like the run examples above):

docker run --rm -p 8080:8080 -v fitter-tokens:/tokens \ -e FITTER_MCP_HTTP_ADDR=:8080 \ -e FITTER_MCP_AUTH_TOKEN=my-secret \ ghcr.io/pxyup/fitter-mcp:latest

Note: 8988 is only for the one-time browser-flow login; the MCP server itself needs no port in stdio mode and only 8080 in hosted HTTP mode.

Logged-in browser sessions in Docker

Browser sessions need the playwright image (the slim one has no browsers). The one-time headed login needs a display, so run it on the host, then bind-mount the session dir into the container (the image pre-creates a writable /sessions):

# on the host: log in once, save the session

fitter_cli browser-login --url https://example.com/login --storage-state ~/.fitter/sessions/example.json

run the MCP server with the sessions dir mounted; configs reference "storage_state_file": "/sessions/example.json"

docker run --rm -i -v ~/.fitter/sessions:/sessions ghcr.io/pxyup/fitter-mcp:playwright

Use a bind mount (not