Comunio

Comunio MCP

An MCP (Model Context Protocol) server for Comunio, the online football fantasy manager.

It gives an AI assistant access to your league — squad, market, offers, standings, transfers — and lets it act on your behalf: bid, sell, set the lineup. One line, client ↔ MCP ↔ Comunio, and this is the middle segment.

Status: in daily use against a real account. Nineteen tools: reading the squad, market, offers, standings and transfers, and acting on the market, bids and lineup. It talks to Comunio's unofficial API, which can change without notice — see docs/comunio-api.md for what is mapped and what is not.

How it works

Tools come in two kinds, and the name tells you which:

Kind	Naming	What it does
Read	get_squad, get_market, get_offers	Query only. Never changes anything. Always safe.
Write	place_bid, accept_offer, set_lineup	Changes your team or spends your money.

Two properties fall out of that:

There is no AI model inside this server, and no strategy either. It translates: it makes Comunio's API callable and its answers legible — unpicking slot numbers, the five different ways one endpoint writes "no data", a ranking field that is 0 for every row. Which player to buy is left to the assistant you are already talking to. No API key, no GPU, no inference cost.

Your client asks before it acts. Every mutating tool declares itself as one, so your MCP client knows to stop and ask you first. The server does not second-guess a move once you have agreed to it, and it reports what Comunio actually answered rather than assuming it worked.

Requirements

• Docker.
• A Comunio account. There is no API key and no sign-up — the server logs in as you.

Nothing else needs to be installed on the host.

Quick start

The image is published, so there is nothing to clone and nothing to build. Put your credentials in a file only you can read, rather than in a command your shell will remember:

install -m 600 /dev/null ~/.comunio.env
$EDITOR ~/.comunio.env      # COMUNIO_USERNAME=you
                            # COMUNIO_PASSWORD=...

claude mcp add comunio -- docker run -i --rm \
  --env-file "$HOME/.comunio.env" \
  ghcr.io/josetorronteras/comunio-mcp

Then ask your assistant how your team is doing — get_account is the quickest proof that the credentials work.

For Claude Desktop, for the uvx route that skips Docker entirely, and for what each variable does, see docs/setup.md.

Documentation

• Setup — running the image and connecting it to an MCP client
• Tools — what each tool returns and what it touches
• Development — layout, dev commands, SDK gotchas
• Architecture — design decisions and the reasoning behind them
• Comunio API — authentication, the link index and what is still unmapped
• MCP protocol notes — the parts of MCP 2026-07-28 that shape this project
• Changelog — what changed in each release

Contributing

Issues and pull requests are welcome. CONTRIBUTING.md covers the setup, what belongs in the server and what does not, and the rules that are not negotiable — no credentials, no tokens and no real account data in a commit. Vulnerabilities go through SECURITY.md rather than a public issue.

Versioning

Releases follow semantic versioning, and what it covers is the MCP surface: tool names, their input schemas, and the fields their responses carry. Renaming a tool, dropping a parameter or removing a field from a response is a major version. Adding a tool, an optional parameter or a field is a minor one.

What it cannot cover is Comunio. This talks to an unofficial API that can change or break without notice, and no version number here can promise otherwise. When it does change, the fix ships as a patch or a minor — the tools stay the same shape.

License

MIT.

Disclaimer

Unofficial project, not affiliated with Comunio. Use it with your own account and at your own risk.