coinvest-mcp

A local MCP server that exposes Liquid Co-Invest's trading-data and order tools to a local LLM. It is a thin, generic proxy: it holds no hardcoded tools — on startup it fetches the tool catalog from your Liquid backend and forwards each call there. All reasoning happens in your local agent; Liquid executes the individual tool calls.

Backend dependency. This client talks to the Liquid Co-Invest backend mcp_api endpoints (GET /api/mcp/tools, POST /api/mcp/dispatch, GET /api/mcp/guide), which must be deployed and enabled for your user.

What it exposes

Whatever the backend registry advertises — market data, balances, portfolio analytics, order status, and trading (spot, perps, prediction markets, and batch orders, plus cancel / close / set leverage). Because the catalog is fetched live, adding or changing a tool on the backend needs no new release here.

It also exposes the authoritative operating guide as the coinvest_operating_guide prompt, fetched live from the backend — load it before driving the tools.

Install

First install uv — this is the only prerequisite. The uvx command used below ships with uv (it's shorthand for uv tool run), so there is nothing else to install:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# or, with Homebrew
brew install uv

Then install and run straight from the repo — no clone required. uvx fetches the package from GitHub, builds it in an isolated environment (provisioning a compatible Python automatically), and runs the coinvest-mcp entry point:

uvx --from git+https://github.com/liquid-public/coinvest-mcp.git coinvest-mcp

The server speaks MCP over stdio, so it's normally launched by your MCP client (see Connect your MCP client) rather than run interactively. The command above is the same one you put in the client config.

Pin to a branch or tag by appending @<ref>:

uvx --from git+https://github.com/liquid-public/coinvest-mcp.git@main coinvest-mcp

To install it once as a persistent tool on your PATH (so the command is just coinvest-mcp), use uv tool instead:

uv tool install git+https://github.com/liquid-public/coinvest-mcp.git
uv tool upgrade coinvest-mcp   # pull a newer version later

[!NOTE] uvx caches the build. After the backend ships changes that only affect this client, force a rebuild with uvx --refresh --from git+https://github.com/liquid-public/coinvest-mcp.git coinvest-mcp.

Configuration

Var	Required	Description
COINVEST_URL	yes	Base URL of the Co-Invest server, e.g. https://coinvest.liquid.trade
COINVEST_MCP_TOKEN	yes	Your MCP token (generate/regenerate it in the Liquid web app)
COINVEST_READONLY	no	1 to hide all write/trading tools
COINVEST_TIMEOUT	no	HTTP timeout in seconds (default 30)

The token can be generated from the Liquid web app (app.liquid.trade).

The token authenticates as you; every call is scoped to your account server-side. One running server == one Liquid user. The token expires after a period (default 30 days) of inactivity (it is refreshed on each use); once expired, requests return 401 and you regenerate it from the Liquid web app.

Connect your MCP client

Point your MCP client at the same uvx command. The client launches the server on demand and passes configuration through env.

Claude Code (CLI)

claude mcp add coinvest \
  --env COINVEST_URL=https://coinvest.liquid.trade \
  --env COINVEST_MCP_TOKEN=your-token-here \
  -- uvx --from git+https://github.com/liquid-public/coinvest-mcp.git coinvest-mcp

Add --env COINVEST_READONLY=1 for a read-only setup.

Claude Desktop / generic MCP client (JSON)

{
  "mcpServers": {
    "coinvest": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/liquid-public/coinvest-mcp.git",
        "coinvest-mcp"
      ],
      "env": {
        "COINVEST_URL": "https://coinvest.liquid.trade",
        "COINVEST_MCP_TOKEN": "your-token-here"
      }
    }
  }
}

For a read-only setup, add "COINVEST_READONLY": "1" to env.

[!NOTE] The client must be able to find uvx on its PATH. If it can't (common on macOS GUI apps), use the absolute path from which uvx as command, e.g. /opt/homebrew/bin/uvx.

Develop

Clone the repo for local development, then sync and test:

git clone https://github.com/liquid-public/coinvest-mcp.git
cd coinvest-mcp
uv sync
uv run pytest

Run your local checkout directly (point the client at this command to test changes before pushing):

uv run --directory /path/to/coinvest-mcp coinvest-mcp

Safety

The local agent owns risk. Liquid runs no server-side agent for these calls — there is no automated margin management, invariant enforcement, or liveness rescue behind them. See the coinvest_operating_guide prompt for the operating contract.