Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@directa-mcp Show me my portfolio overview and current positions."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server exposing Directa SIM's Darwin API (dAPI) to any MCP client — positions, balance, orders, historical data.
simoneb.github.io/directa-mcp carries the config for the current release, ready to copy, and a one-click extension for Claude Desktop.
Darwin listens on 127.0.0.1 only while it is running and logged in, so this is a local stdio server: your client starts it on the same machine. Hosts that only accept remote HTTP servers cannot run it (ChatGPT web and desktop among them; use Codex CLI there). There are no API keys — the authentication is Darwin being logged in.
An active Directa account, with Darwin installed (needs a Java JRE) and logged in.
API access enabled: sign the disclaimer on directatrading.com, then check Sviluppatori > Dev kit in Darwin.
For candles and ticks only: the real-time data entitlement. Without it those tools fail with 1032, and get_darwin_status reports it as datafeed_enabled.
Related MCP server: tradier-mcp
Pick a tag from the releases — the latest unless you have a reason — and substitute it for <TAG>. uvx fetches and runs the server in an isolated environment; only uv is needed.
{
"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"
}
}
}
}Client | File |
Claude Desktop |
|
Cursor |
|
Windsurf |
|
Gemini CLI |
|
VS Code keys it under servers and wants "type": "stdio", in .vscode/mcp.json. Codex CLI takes TOML in ~/.codex/config.toml:
[mcp_servers.directa]
command = "uvx"
args = ["--from", "https://github.com/simoneb/directa-mcp/archive/refs/tags/<TAG>.tar.gz", "directa-mcp"]
[mcp_servers.directa.env]
DIRECTA_ENABLE_ORDERS = "false"Or let the client write it: claude mcp add, codex mcp add, code --add-mcp.
Pin a tag, not a branch — otherwise every start pulls the tip of master. Prefer the archive URL over git+https://…: the git form needs a git on PATH, and some clients hand the server too small an environment to find one.
Tool | |
| Are Darwin's ports up; |
| Connection state, release, whether the datafeed is enabled |
| Liquidity, open P&L, equity |
| Buying power, with and without margin |
| Open positions, as Darwin reports them |
| Positions with derived price and value, totals, and a reconciliation check |
| The day's orders with decoded state; |
| What an order would cost, without placing it |
| Real orders. Need the gate below |
| Launches dGO so you can log in. Needs |
| OHLC candles and ticks. Need the datafeed entitlement |
Symbols use Directa's formats: ENI.MI for Borsa Italiana stocks, bare tickers for ETFs (VWCE), M.<number> for bonds. Read one back from get_positions rather than guessing.
Each tool carries the protocol's annotations (readOnlyHint and friends), so a client can group them by permission and only ask for approval where it matters. The twelve reading tools are marked read-only; the six that put a command on the wire are not — including preview_limit_order, which places nothing but does send ACQAZ.
Order tools work only with DIRECTA_ENABLE_ORDERS=true. Otherwise they send nothing and return success: false with blocked: true.
There is no simulated mode. The dAPI has no command that accepts an order without sending it to market, and Directa provides no test account, so any library offering one for this API is fabricating the responses. The flag is a safety catch, not a mode selector: it lives in the process configuration, so the model cannot turn it on — only you can. With it on, orders are real, with real money.
With DIRECTA_AUTOSTART=true the server exposes start_darwin, which launches dGO; Darwin itself has no installed executable. For it to get past dGO's tile grid, set AutoSelezione to "Darwin 2" in dGO's Preferenze — the server writes no settings of its own.
Darwin then asks for an OTP, so the tool does not wait: it returns once dGO is up and you finish the login, after which check_connection reports running. It launches only from stopped, since Directa allows one session at a time, and never closes Darwin. For the same OTP reason this server cannot run unattended.
INFOACCOUNT field names do not describe their contents. gain_euro is the open P&L; open_profit_loss is the portfolio's carrying cost. Reading it as a gain overstates it by nearly an order of magnitude.
Bonds are quoted as a percentage of nominal. 20,000 nominal at 95.0 is worth €19,000, not €1,900,000 — the naive quantity × price is wrong by 100×. get_portfolio_overview handles this and reconciles its own totals against Darwin's; if reconciliation.reconciled is false, don't present the numbers as fact.
The client is one dependency-light file, src/directa_mcp/dapi.py. Every command and response format it uses, and the surprises behind them, are in docs/PROTOCOL.md. The project began on the community library directa-api-python, dropped after live testing — see docs/UPSTREAM.md.
Cancel every open order for a symbol. Confirm the symbol with the user first — this affects orders the user may not have asked about. Same order gate as place_limit_order.
The symbol filter is verified: with working orders on two symbols, this
revoked only the one named. Darwin answers REVALL with a single TRADOK
3002 that carries the id of the order it revoked, not the symbol asked
about, so read the resulting order list rather than the ack to learn what
went.
Inputs: symbol (required). Returns: object
Cancel one open order by the order_id shown in get_orders. Same order gate as place_limit_order.
Inputs: order_id (required). Returns: object
Check whether Darwin's local trading and historical-data ports are reachable. Call this first if any other tool fails: it distinguishes "Darwin is not running" from "Darwin refused the command", and needs only Darwin running and listening, not the account logged in.
darwin.state is running, starting or stopped, and darwin.hint says what
to do about it. This is also the tool to poll after start_darwin, once the
user says they have finished the login.
Inputs: no named parameters. Returns: object
Get raw account figures from dAPI INFOACCOUNT: liquidity, equity and two fields whose documented names do not match their contents.
gain_euro is the open P&L, and open_profit_loss is the portfolio's cost
basis, not a profit — both verified by reconciliation. Do not quote
open_profit_loss as a gain. For anything about portfolio value or
performance prefer get_portfolio_overview, which derives the figures and
checks them; use this tool for liquidity, equity, the account code, or when
the user wants the raw line.
Inputs: no named parameters. Returns: object
Get buying power: cash available for stocks and derivatives, with and without margin (dAPI INFOAVAILABILITY). Use this rather than get_account_balance when the question is "how much can I invest".
Inputs: no named parameters. Returns: object
Get OHLC candles within an explicit range. Dates as YYYYMMDDHHMMSS (e.g. 20260810093000); period_seconds sets the bucket (60=1min, 300=5min, 3600=1hr, 86400=1day). Needs the real-time quote entitlement.
Inputs: symbol (required), end_date (required), start_date (required), period_seconds. Returns: object
Get daily OHLC candles for the last N days. Needs the real-time quote entitlement — without it this fails with code 1032.
Inputs: symbol (required), days. Returns: object
Get Darwin's connection status, release, and whether the real-time
datafeed is enabled. Richer than check_connection since it goes through the
dAPI conversation rather than a raw TCP probe. The datafeed_enabled field
tells you in advance whether the historical tools can work at all.
Inputs: no named parameters. Returns: object
Get intraday OHLC candles bucketed by period_minutes over the last N days. Needs the real-time quote entitlement (code 1032 without it).
Inputs: symbol (required), days, period_minutes. Returns: object
Get orders placed today with their state — "In negoziazione" (working), "Eseguito" (filled), "Revocato" (cancelled), and so on.
A symbol usually carries several order records with different states, so
read the status field before describing an order as open; set
pending_only=True for just the ones still working.
Inputs: symbol, pending_only. Returns: object
The whole picture in one call: every position with its current price and value, plus portfolio totals and P&L. Prefer this over get_positions when the question is about how the portfolio is doing or what it is worth.
Darwin does not report a current price, so price and value are derived from
the average price and the theoretical gain. Do not compute values yourself
from get_positions: bonds (symbols starting M.) are quoted as a
percentage of nominal, so quantity times price overstates them 100-fold.
This tool handles that and then checks its own arithmetic against Darwin's
reported figures — if reconciliation.reconciled is False, say so and quote
the residual rather than presenting the totals as fact.
Inputs: no named parameters. Returns: object
Get a single position by symbol, as it appears in get_positions.
Inputs: symbol (required). Returns: object
Get every open position in the portfolio, with quantity, average price and theoretical gain. Returns the complete list.
Inputs: no named parameters. Returns: object
Get tick-by-tick trades over the last N days. Can be very large — prefer get_intraday_candles beyond a single session. Needs the real-time quote entitlement.
Inputs: symbol (required), days. Returns: object
Change the limit price of an open order (signal_price applies only to
stop orders). Confirms in the same exchange, like place_limit_order, and
reports on_market. Same order gate.
Inputs: price (required), order_id (required), signal_price. Returns: object
Place a REAL limit order with real money. There is no simulation mode. Disabled unless the server runs with DIRECTA_ENABLE_ORDERS=true.
Prefer preview_limit_order first: it reports the commission and the exact instrument Darwin matched, without placing anything.
Darwin requires a two-step submit-then-confirm exchange, and both steps
happen inside this one call because a pending confirmation does not survive
the connection that produced it. Read on_market in the response to know
whether the order is actually working — an exchange that completes without
error has still placed nothing if confirmation did not go through. Then
verify with get_orders rather than trusting the acknowledgement.
order_id is the client-side reference Darwin echoes back; one is generated if omitted.
Inputs: side (required), price (required), symbol (required), quantity (required), +1 more. Returns: object
Ask Darwin what an order would cost, without placing it. Use this before place_limit_order, and whenever the user asks about commissions.
The order is submitted and deliberately left unconfirmed, so it never reaches the market, and Darwin answers with its pre-trade disclosure: the instrument's full name, the amount, the commission that would apply, and any conflict-of-interest note. This is the only way to obtain commission figures — no dAPI command reports them, and they depend on the order's value, so they cannot be looked up in advance.
Read on_market in the response before describing the outcome. It should be
false. If it is true, Darwin was not configured to ask for confirmation and
the order IS live — say so immediately and prominently.
Subject to the same DIRECTA_ENABLE_ORDERS gate as place_limit_order, since this does send an order command to a real account.
Inputs: side (required), price (required), symbol (required), quantity (required), +1 more. Returns: object
Launch dGO, Directa's launcher, so the user can bring Darwin up. Needs the server to have been started with DIRECTA_AUTOSTART=true.
This does not finish the job and does not wait: Darwin requires an OTP, so the call returns as soon as dGO is running and the user takes it from there. Tell them to complete the login (and, if dGO stops on its tile grid rather than opening Darwin, that AutoSelezione must be set to "Darwin 2" in dGO's Preferenze), then call check_connection to see whether the ports have opened. Do not call this repeatedly while waiting — Directa allows one session at a time, and a second dGO can disturb the login in progress.
Since it puts a window and an OTP prompt in front of the user, never call it on your own initiative to repair a failed tool: propose it and let the user ask for it.
Inputs: no named parameters. Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 18 tools
Most tools map cleanly to distinct resources and actions, and the descriptions explicitly steer agents toward the right one. A few close pairs—check_connection vs get_darwin_status and get_positions vs get_portfolio_overview—could be confused based on names alone, but the descriptions resolve the boundaries.
All tool names follow a consistent snake_case verb_noun pattern: get_, start_, check_, preview_, place_, modify_, and cancel_. Even the status-style tools read predictably, and there is no mixing of conventions.
At 18 tools, this is slightly above the ideal 3-15 range, but the count is justified by the breadth of the domain: connection lifecycle, account, positions, orders, and market data each have their own focused tools. No tool feels redundant or purely decorative.
The core workflows are well covered: check/start Darwin, read balances and positions, preview/place/modify/cancel orders, and fetch candle/tick data. Minor gaps such as no market-order tool, no execution history, and only today's orders are workable but keep it from being fully complete.
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
MCP server for OpenMM — exposes market data, account, trading, and strategy tools to AI agents
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server for Gainium — manage trading bots, deals, and balances via AI assistants
