gunio-mcp

A local-only, Docker-packaged MCP server (and a thin read CLI) for gun.io, authenticated with your own browser session — the same host-side cookie-broker + wrapper pattern as claudesync. It lets an MCP client (Claude Code, etc.) read your gun.io freelancer data — interviews, applications, jobs, profile — and perform a small set of gated writes.

Unofficial. No affiliation with gun.io. This talks to gun.io's private, undocumented API using your logged-in session. It is a personal automation tool; use it at your own risk and within gun.io's Terms of Service. No gun.io code is included in this repo.

How it works

Firefox session ──(host-side broker: rookie-cli)──▶ GUNIO_COOKIE ──▶ docker run ──▶ FastMCP server ──▶ app.gun.io/api/v2

• A cookie broker (scripts/lib/harvest-cookie.sh) reads your gun.io session (sessionid + csrftoken) from the browser, host-side. Nothing leaves your machine.

• A thin wrapper passes that cookie into a container via the GUNIO_COOKIE env var and docker runs it per invocation.

• Inside the container, a Python/FastMCP server (gunio_mcp) calls gun.io's /api/v2 through a safety-guarded client (gunio_broker).

Related MCP server: Upwork MCP Server

Security model

• Reads need only the cookies. Writes echo the csrftoken as X-CSRFToken (Django CSRF), and are double-gated: a call previews unless confirm=true and the server env has GUNIO_MCP_WRITE_SCOPE set.

• Hard denylist in the client, enforced regardless of tool: auth/logout (a GET that kills your session), the entire /staff/ tree, DELETE on a freelancer (account deletion), complete-screening, and telemetry writes.

• Cookies are never logged or placed in exceptions.

• Local only. No data is sent anywhere except gun.io itself.

Install (once Docker image + installer land)

# bootstrap the broker + wrappers, pull the image
scripts/gunio-setup.sh install

# register the MCP server with Claude Code
claude mcp add --scope user gunio ~/.local/share/gunio/gunio-mcp-wrapper.sh

To enable writes, set GUNIO_MCP_WRITE_SCOPE=writes in the server env (see the wrapper). Without it, write tools only ever return a dry-run preview.

Remote mode (--serve)

By default gunio-mcp speaks MCP over stdio for a local client. With --serve it instead runs FastMCP's streamable HTTP transport as a long-lived service:

gunio-mcp --serve                      # http://127.0.0.1:8000/mcp
gunio-mcp --serve --host 0.0.0.0 --port 9000

Configuration (flags win over env vars):

Naming convention: GUNIO_MCP_* vars configure the server process itself; GUNIO_* vars (today just GUNIO_COOKIE) configure the gun.io account/session.

Endpoint security

GUNIO_COOKIE authenticates the server TO gun.io; nothing inherent authenticates clients TO this server. Anyone who can reach the HTTP endpoint can act as your gun.io account, including gated writes if the write scope is set. Therefore:

• Set GUNIO_MCP_AUTH_TOKEN to require Authorization: Bearer <token> on every request (compared in constant time; never logged).

• Binding a non-loopback host without that token refuses to start, unless you explicitly set GUNIO_MCP_INSECURE=1 because the network layer (e.g. Tailscale or an authenticating proxy) already provides access control.

• Do NOT set GUNIO_MCP_WRITE_SCOPE on a remote deployment unless GUNIO_MCP_AUTH_TOKEN is configured.

Bearer auth applies only to serve mode; the stdio default ignores these vars.

Docker

docker run -e GUNIO_COOKIE=... -e GUNIO_MCP_AUTH_TOKEN=... -p 8000:8000 \
  gunio-mcp:local --serve --host 0.0.0.0

Inside a container, binding 0.0.0.0 with the token set is the expected pattern.

Operational caveat: the cookie is a deploy-time secret

In remote mode there is no host-side broker refreshing the session: the GUNIO_COOKIE you deploy with is it. When gun.io expires that session, reads start failing until the deployment is updated with a fresh cookie. The auth_status tool (or gunio auth status on the CLI) is how you detect this: it performs one lightweight authenticated read and reports

{"mode": "cookie", "authenticated": false, "checked_at": "...", "error": "gun.io returned HTTP 401"}

without ever raising raw errors or leaking cookie material. Phase 2 will add credential-based login; this release is transport + visibility only.

Develop

uv sync --extra dev
uv run --extra dev pytest -q          # full suite
uv run gunio me                       # thin CLI (needs GUNIO_COOKIE or a logged-in browser)
uv run gunio-mcp                      # run the MCP server over stdio

GUNIO_COOKIE is a sessionid=...; csrftoken=... string; the broker produces it, or set it by hand for local dev.

Layout

License

MIT.