@tiny-fish/mcp

TinyFish MCP server: web search, page fetching and extraction, browser automation and page monitoring for Claude, Cursor, VS Code and any MCP client. Search and Fetch are free.

Using Claude or ChatGPT in the browser or desktop app? Skip the setup and add the official TinyFish plugin for Claude or ChatGPT in one click. It bundles these tools with ready-made skills and safety rules.

This package is a transparent reverse proxy that exposes a local Streamable-HTTP MCP endpoint at http://127.0.0.1:3711/mcp and forwards every request to the hosted TinyFish MCP server at https://agent.tinyfish.ai/mcp.

The proxy defines no tools and no schemas of its own. tools/list, tools/call, resources/*, errors, and the run_web_automation SSE progress stream all come from the hosted server: streaming (SSE) responses are relayed byte-verbatim, and non-streaming JSON responses are relayed content-identical (parsed and re-serialized, deep-equal to upstream). What the hosted server says is what your client sees.

Tools

The hosted server exposes 28 tools. You can use them to search the web, fetch and extract pages, automate browsers, run remote Chrome sessions (CDP), keep signed-in Browser Context Profiles and schedule page and topic Monitors.

| Category | Tools | |---|---| | Search & Fetch | search, fetch_content | | Web automation | run_web_automation, run_web_automation_async, get_run, list_runs, cancel_run, batch_status, batch_cancel | | Browser sessions | create_browser_session, list_browser_sessions, close_browser_session | | Browser Context Profiles | create_profile, list_profiles, start_profile_setup_session, save_profile_setup_session, cancel_profile_setup_session | | Monitors | create_monitor, get_monitor, list_monitors, run_monitor, pause_monitor, resume_monitor, cancel_monitor | | Account & usage | get_wallet, get_search_usage, list_fetch_usage, guide_next_step |

• Tool reference: every tool, verbatim, with parameters
• Examples: common workflows and prompts
• MCP Integration guide: client setup, auth, rates, troubleshooting
• Full documentation: docs.tinyfish.ai

Use the hosted server first

If your MCP client supports remote Streamable-HTTP servers (Claude Code, Claude Desktop connectors, Cursor, VS Code, and most modern clients do), connect it directly to the hosted server — no install, no local process:

https://agent.tinyfish.ai/mcp

Use this package instead when:

• your client only talks to local MCP servers, or
• you want to authenticate with a TinyFish API key from your environment instead of the hosted server's OAuth flow (CI, headless machines, scripts).

Install

npm install -g @tiny-fish/mcp

Or run it without installing:

npx @tiny-fish/mcp

Requires Node.js >= 22. (This is a deliberate deviation from the TinyFish CLI's >=24 requirement — nothing here needs Node 24.)

API key

The server reads TINYFISH_API_KEY from its environment at startup and sends it upstream as X-API-Key on every call. Get a key at https://agent.tinyfish.ai.

export TINYFISH_API_KEY=tf_...
tinyfish-mcp

On success it prints one line to stderr:

tinyfish-mcp [info] listening on http://127.0.0.1:3711 — upstream https://agent.tinyfish.ai/mcp — v0.1.0

The key is never logged and never echoed back to clients.

Client configuration

Start tinyfish-mcp (e.g. in a terminal, or under your process manager of choice), then point your client at http://127.0.0.1:3711/mcp.

Claude Code

claude mcp add --transport http tinyfish http://127.0.0.1:3711/mcp

Claude Desktop

Settings → Connectors → Add custom connector, with URL http://127.0.0.1:3711/mcp. On versions whose claude_desktop_config.json supports URL-based servers:

{
  "mcpServers": {
    "tinyfish": {
      "url": "http://127.0.0.1:3711/mcp"
    }
  }
}

Note: Claude Desktop can also use the hosted https://agent.tinyfish.ai/mcp directly as a custom connector — prefer that unless you need API-key auth.

Cursor

~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "tinyfish": {
      "url": "http://127.0.0.1:3711/mcp"
    }
  }
}

VS Code

.vscode/mcp.json:

{
  "servers": {
    "tinyfish": {
      "type": "http",
      "url": "http://127.0.0.1:3711/mcp"
    }
  }
}

Any other client

Configure a Streamable-HTTP (remote/URL) MCP server with:

{ "url": "http://127.0.0.1:3711/mcp" }

The endpoint accepts POST /mcp only (matching the hosted server, which has no GET SSE channel and no DELETE session teardown). GET /healthz returns 200 ok for debugging.

Environment variables

| Variable | Default | Description | |---|---|---| | TINYFISH_API_KEY | (required) | TinyFish API key, sent upstream as X-API-Key. The server refuses to start without it. | | PORT | 3711 | Local listen port (integer 1-65535). No auto-increment: if the port is busy the server exits with an error. | | TINYFISH_UPSTREAM_URL | https://agent.tinyfish.ai/mcp | Upstream MCP URL. Must be https:; http: is allowed only for 127.0.0.1/localhost (local testing). |

The proxy also sends attribution headers on every upstream call: X-TF-Request-Origin: tinyfish-mcp, X-TF-Client-Name: tinyfish-mcp, and X-TF-Client-Version: <package version>.

Security & trust model

This is a loopback-only server with a deliberate, documented trust boundary:

• Loopback bind, always. The server binds the 127.0.0.1 literal and this is not configurable — it can never listen on 0.0.0.0 or a LAN interface.
• Origin validation. Requests carrying an Origin header are rejected with 403 unless the origin is http(s)://127.0.0.1 or http(s)://localhost (any port). This blocks the DNS-rebinding attack the MCP spec calls out for local HTTP servers. Requests without an Origin header (curl, MCP SDKs, inspectors) are allowed.
• Server-holds-key. The process reads TINYFISH_API_KEY from its env; clients send no credential on the local hop. This is the simplest model, but it means any local process that can reach 127.0.0.1:<port> can use your key and drive automations (which can spend TinyFish credits). The loopback bind and Origin check are the mitigations; treat the port as a local trust boundary on a machine you trust.

Troubleshooting

"Port 3711 is already in use" — another process holds the port. Stop it, or set PORT to a free port and update your client config to match.

HTTP 502 with JSON-RPC error -32001 ("Upstream rejected the request … check that TINYFISH_API_KEY is set to a valid TinyFish API key") — the hosted server rejected your key. Verify TINYFISH_API_KEY is set in the environment of the tinyfish-mcp process (not just your shell) and that the key is valid at https://agent.tinyfish.ai. The error's data carries the upstream status and (truncated) body for diagnosis.

HTTP 502 with JSON-RPC error -32000 ("cannot reach …") — the upstream server is unreachable: check your network/proxy/VPN; the hosted server may also be temporarily down. If you overrode TINYFISH_UPSTREAM_URL, check it. If a streamed run_web_automation call fails mid-stream you get the same -32000 as the final SSE frame, with a "the run may still be executing" warning and the runId when known — check the run's status instead of retrying blindly.

Batch requests don't work — MCP forbids JSON-RPC batching and the hosted server does not support batch arrays. The proxy forwards a batch as-is and the upstream answers its own error; send one JSON-RPC message per request.

Claude/other client can't connect — make sure tinyfish-mcp is actually running (it's a standalone server; clients do not launch it) and that GET http://127.0.0.1:3711/healthz answers ok.

Development

npm ci
npm run build        # tsc → dist/, marks dist/index.js executable
npm test             # unit tests (offline, mock upstream)
npm run test:watch   # unit tests in watch mode
npm run lint         # eslint over src/ tests/
npm run format       # prettier
npm run type-check   # tsc --noEmit over the whole tree

Layout: src/core/ is the transport-agnostic proxy core (upstream client, session bridge, SSE relay, error shaping); src/http/ is the thin HTTP adapter (routing, Origin check); tests/ holds the unit suites plus tests/helpers/mock-upstream.ts, a mock of the hosted endpoint that the unit tests run against entirely offline.

Integration tests hit the real hosted upstream and are gated: without TINYFISH_API_KEY they skip with a printed notice.

TINYFISH_API_KEY=... npm run test:integration

Set TINYFISH_UPSTREAM_URL to point them at a sandbox deployment instead of production. Note the run_web_automation integration test executes a real automation and spends credits.

Maintenance

Maintained by @Zechereh. Bugs and feature requests: GitHub issues.

License

MIT