directa-mcp

MCP server exposing Directa SIM's Darwin API (dAPI) to Claude — positions, balance, orders, historical data.

Local, not cloud

Darwin opens TCP sockets on 127.0.0.1 (10002 trading, 10003 historical) only while the app is running and logged in. So this is a local stdio server, launched by Claude Desktop or Claude Code on the same machine as Darwin — not a remote connector.

There are no API keys to configure: the authentication is Darwin being logged in on your machine.

Related MCP server: tradier-mcp

Prerequisites

1. An active Directa account.

2. Darwin installed (needs a Java JRE/JDK) and logged in.

3. API access enabled: sign the disclaimer in the reserved area on directatrading.com, then check Sviluppatori > Dev kit in Darwin.

4. Historical tools (candles, ticks) additionally need the real-time quote entitlement. Without it every historical command answers 1032 — datafeed non abilitato; get_darwin_status reports this up front as datafeed_enabled.

Install

uvx fetches the package, provisions a suitable Python and runs it in an isolated environment — only uv is needed, no clone and no virtualenv. Pick a tag from the releases, ideally the latest, and substitute it for <TAG> below.

Claude Code:

claude mcp add directa --scope user -- uvx --from "https://github.com/simoneb/directa-mcp/archive/refs/tags/<TAG>.tar.gz" directa-mcp

Claude Desktop — add to %APPDATA%\Claude\claude_desktop_config.json and restart the app:

{
  "mcpServers": {
    "directa": {
      "command": "uvx",
      "args": [
        "--from",
        "https://github.com/simoneb/directa-mcp/archive/refs/tags/<TAG>.tar.gz",
        "directa-mcp"
      ],
      "env": {
        "DIRECTA_ENABLE_ORDERS": "false"
      }
    }
  }
}

Pin a tag rather than a branch: without one every start would pull the tip of master, which is not what you want from a tool that talks to your account. To upgrade, change the tag.

Prefer the archive URL over git+https://…. The git form makes uvx shell out to git, and Claude Desktop starts MCP servers with no PATHEXT in the environment — so the executable lookup fails with Git executable not found even where git is installed and on PATH.

Working from source (to develop the server, not to use it):

uv venv
uv pip install -e ".[dev]"
pytest

Tests run against a fake Darwin over sockets, so the platform need not be running. Then register the venv's Python by absolute path — Claude starts the process with its own environment, without the venv active:

claude mcp add directa-dev --scope user -- <repo>\.venv\Scripts\python.exe -m directa_mcp.server

Usage

The tools describe themselves, so ask in plain language: how the portfolio is doing, which positions are down, whether there are open orders, how much is available to invest, whether Darwin is connected.

Current prices for arbitrary symbols, and charts, do not work without the datafeed entitlement. Prices for your positions do — those are derived from the portfolio.

Don't ask Claude to compute values from get_positions: quantity × price is wrong by 100× on bonds. get_portfolio_overview handles the convention and reconciles its own arithmetic against Darwin's figures; when reconciliation.reconciled is false the totals are not to be presented as fact.

The order gate

Tools that place, modify or cancel orders work only when the server runs with DIRECTA_ENABLE_ORDERS=true. Otherwise they send nothing at all to Darwin and return success: false with blocked: true.

There is no simulated mode, and that is not this project's choice: the dAPI has no command that accepts an order without sending it to market, and Directa states plainly that it provides no test account for developing external applications. So any library offering a "simulation mode" for this API is inventing the responses client-side — which is exactly what the previous version of this server did, returning a plausible acknowledgement for an order that never left.

The flag is therefore a safety catch, not a mode selector. It lives in the MCP process configuration, so the model cannot turn it on — only you can, by editing the config and restarting. Which also means you can register the server for portfolio questions and leave the whole trading surface inert.

With the flag on, orders are real, with real money.

cancel_all_orders is deliberately unverified: it is the one operation that can touch orders this server did not create, so a broken symbol filter would revoke something else.

Starting Darwin

With DIRECTA_AUTOSTART=true the server exposes start_darwin, which launches dGO, Directa's launcher. It cannot launch Darwin directly: Darwin has no installed executable, only a jar that dGO downloads and starts with a session token reissued at every login, so that command line is not repeatable.

For it to reach Darwin instead of stopping at dGO's tile grid, set AutoSelezione to "Darwin 2" in dGO's Preferenze. The server does not write that setting, or anything else on the machine — no files, no registry keys, no process it did not start itself.

A human stays in the path: Darwin asks for an OTP. So the tool does not wait — it returns as soon as dGO is up, and you complete the login. From there check_connection reports one of three states:

start_darwin launches only in stopped. Directa allows one session at a time, and a second dGO risks dropping the login in progress. It never closes Darwin, and there is no stop_darwin: shutting down a platform that may have working orders on the book is not a decision to automate.

The flag is separate from DIRECTA_ENABLE_ORDERS on purpose — starting the platform and being allowed to send it orders are two distinct consents.

Note that the ports open a few seconds before the connection is established: in that window get_darwin_status answers CONN_UNAVAILABLE with the ports already reachable. That is startup in progress, not a fault.

Because the OTP is mandatory, this server cannot be automated unattended — cron jobs, scheduled agents. Someone has to type the code.

Tools

Three symbol formats coexist: ENI.MI for Borsa Italiana stocks, bare tickers for ETFs (VWCE, IWDA), M.<number> for bonds. Read the format back from get_positions rather than guessing at it.

Each tool carries the protocol's annotations — readOnlyHint, destructiveHint, idempotentHint, openWorldHint — so a client can sort them into permission groups instead of one undifferentiated list, and ask for approval only where it matters. The twelve reading tools are marked read-only; the six that put a command on the wire are not. preview_limit_order is the one worth knowing about: it places nothing, but it does send ACQAZ, so it is annotated as a write rather than flattered into the read-only group.

Two data traps

INFOACCOUNT field names do not describe their contents. Measured against the portfolio, gain_euro is the open P&L, while open_profit_loss is the portfolio's carrying cost, reconciled to the cent. Reading it as a gain overstates it by nearly an order of magnitude. The names stay Directa's rather than invented ones, and every response carries its raw line.

Bonds are quoted as a percentage of nominal. In STOCK;M.100001;10:00:00;20000;0;0;95.0;200 the quantity is 20,000 of nominal and the price is 95.00% of it: the position is worth €19,000, not €1,900,000. The naive calculation is wrong by 100×.

Implementation

The dAPI is line-oriented text and the client lives in one file, src/directa_mcp/dapi.py, with no dependencies beyond mcp and python-dotenv. Every command and response format it uses is documented in docs/PROTOCOL.md, together with the raw transcripts it was derived from.

Framing is deterministic via FLOWPOINT TRUE, which wraps lists in BEGIN/END markers, so a response is read up to its terminator instead of waiting for the socket to fall quiet; replies are selected by prefix and everything else is routed to unsolicited. If Darwin refuses FLOWPOINT, the client refuses to start rather than guess where a portfolio ends.

The project began on the community library directa-api-python, dropped after testing against live Darwin — see docs/UPSTREAM.md for the three defects and the fixes proposed upstream.