oanda-mcp
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., "@oanda-mcp show me the current EUR/USD price"
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.
oanda-mcp
MCP server for the Oanda v20 REST API (forex/CFD trading): account state, candles, live pricing, order books, orders, trades, positions, and transaction history. It defaults to the practice environment, and the trading (write) tools are not registered at all unless explicitly enabled — a client connected to the default configuration cannot see or call them.
Features
Read-first by design — 22 read tools cover accounts, market data, pricing, orders, trades, positions, and transaction history; the 7 write tools exist only when
OANDA_MCP_ENABLE_TRADINGis set.Practice environment by default — the live host is opt-in via
OANDA_ENV=live.Trimmed responses — tools return the fields a trader acts on (prices, units, P/L, timestamps), not raw API dumps; list tools accept a
limitparameter.v20 conventions preserved — prices and monetary values are decimal strings, timestamps are RFC3339, units are signed (positive = long, negative = short).
Credentials stay in the environment — the token travels only in the
Authorizationheader, and error messages never echo header or credential values.Rate-limit aware — HTTP 429 responses are retried once, honouring
Retry-After.
Related MCP server: ibkr-mcp
Tools
Read tools (always registered)
Tool | Description |
| List the accounts authorized for the configured API token |
| Full state of the configured account, trimmed to summary level |
| Lightweight account summary: balance, NAV, margin headroom |
| Instruments tradeable on the account, with pip location, display precision, trade size limits, and margin rate |
| Poll for order/trade/position changes since a transaction ID |
| OHLC candles for an instrument at any granularity (S5 through monthly) |
| Aggregate pending-order book snapshot around the current price |
| Aggregate open-position book snapshot around the current price |
| Current bid/ask/spread for one or more instruments |
| Most recent candle per instrument/granularity specification |
| Orders on the account, filterable by instrument and state |
| Every pending order on the account |
| A single order by ID or client-assigned ID |
| Trades on the account, filterable by instrument and state |
| Every open trade, with attached take-profit/stop-loss orders |
| A single trade by ID or client-assigned ID |
| Every position ever held, one per instrument, with lifetime P/L |
| Positions with at least one open trade |
| The account's position for one instrument |
| Transaction page links for a time range (fetch pages with |
| A single transaction by ID |
| The transactions in an inclusive ID range |
Write tools (registered only when OANDA_MCP_ENABLE_TRADING is set)
Tool | Description |
| Change the account alias and/or account-wide margin rate |
| Create a MARKET/LIMIT/STOP/MARKET_IF_TOUCHED order with optional take profit / stop loss / trailing stop on fill |
| Replace a pending order atomically (cancel + create) |
| Cancel a pending order |
| Close an open trade, fully or partially, with a market order |
| Create, replace, or cancel a trade's take profit, stop loss, and trailing stop |
| Close the long and/or short side of an instrument's position |
Configuration
All configuration comes from environment variables — no config files, no flags carrying secrets.
Variable | Default | Purpose |
| — (required) | Personal access token, sent as |
| first authorized account | Account to operate on |
|
|
|
| off |
|
Getting started
Run straight from the repository with uv:
uvx --from git+https://github.com/florinel-chis/oanda-mcp oanda-mcpThe server speaks stdio by default; pass --transport http --host 127.0.0.1 --port 8000 to serve
streamable HTTP at /mcp instead.
Warning: the HTTP endpoint has no authentication — anyone who can reach the port can call every registered tool with your
OANDA_API_TOKEN's privileges. The server therefore refuses to bind a non-loopback--hostunless--allow-remoteis also passed; only use that flag behind an authenticated reverse proxy or an otherwise-restricted network (such as the Docker port-mapping below).
MCP client configuration
Add the server to your MCP client's configuration (the exact file location depends on the client):
{
"mcpServers": {
"oanda": {
"command": "uvx",
"args": ["--from", "git+https://github.com/florinel-chis/oanda-mcp", "oanda-mcp"],
"env": {
"OANDA_API_TOKEN": "your-token",
"OANDA_ENV": "practice"
}
}
}
}Or run the Docker image (build it first, see below):
{
"mcpServers": {
"oanda": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "OANDA_API_TOKEN", "-e", "OANDA_ENV", "oanda-mcp"],
"env": {
"OANDA_API_TOKEN": "your-token",
"OANDA_ENV": "practice"
}
}
}
}Docker
docker build -t oanda-mcp .
# stdio (for MCP client configs)
docker run -i --rm -e OANDA_API_TOKEN oanda-mcp
# streamable HTTP at http://127.0.0.1:8000/mcp
# (-p 127.0.0.1:8000:8000 keeps the unauthenticated endpoint off external interfaces;
# --host 0.0.0.0 refers to interfaces inside the container and is required for the
# port mapping to work, hence --allow-remote — the host-side bind stays loopback-only)
docker run --rm -p 127.0.0.1:8000:8000 -e OANDA_API_TOKEN \
oanda-mcp --transport http --host 0.0.0.0 --port 8000 --allow-remoteSafety
The server talks to the practice environment unless
OANDA_ENV=liveis set.Trading tools are hidden unless
OANDA_MCP_ENABLE_TRADINGis set — they are never registered, not merely rejected, so MCP clients cannot discover or call them.The HTTP transport is unauthenticated: anyone who can reach the port can call every registered tool — read balances and positions always, and place or close orders when trading is enabled — using your API token's privileges. Keep it bound to
127.0.0.1(the stdio transport has no such exposure), or front it with an authenticated proxy if remote access is genuinely needed.Order placement has a sharp edge: the API can accept an order and cancel it in the same response — a FOK market order, for example, is cancelled for
INSUFFICIENT_MARGINorMARKET_HALTED. The order tools surface the cancel transaction so this is visible, but always check it before treating an order as filled.Trading leveraged products is risky. Use at your own risk, and test everything against a practice account first.
Development
uv sync
uv run pytest
uv run ruff check .Tests are hermetic: all HTTP is mocked with respx and the server is exercised through the
in-memory FastMCP client. No credentials or network access are needed to run them. A manual,
read-only smoke check against a real practice account lives at scripts/smoke.py.
License
MIT — see LICENSE.
Available Tools
22 toolsget_accountARead-only
Get the full state of the configured account, trimmed to summary level.
Returns {"account": {...}, "lastTransactionID": "..."}. The account
object carries monetary fields as decimal strings in the account's home
currency (balance, NAV, pl, unrealizedPL,
marginUsed, marginAvailable, ...), the leverage setting
marginRate (decimal string, e.g. "0.02" = 50:1), the open-item
counts (openTradeCount, openPositionCount,
pendingOrderCount), and createdTime as an RFC3339 timestamp.
The per-order/trade/position detail lists the API embeds here are
dropped; use the orders, trades, and positions tools for those.
For a cheaper request that yields the same fields, prefer
get_account_summary.
Inputs: no named parameters. Returns: object
get_account_changesARead-only
Poll the configured account for state changes since a transaction.
Returns {"changes": {...}, "state": {...}, "lastTransactionID": "..."}. changes groups what happened (ordersCreated,
ordersCancelled, ordersFilled, ordersTriggered,
tradesOpened, tradesReduced, tradesClosed, positions,
transactions); state carries the price-dependent snapshot
(account unrealizedPL, NAV, marginUsed, plus per-trade,
per-position, and per-order dynamic state). Feed the returned
lastTransactionID back as since_transaction_id on the next
call. Timestamps are RFC3339; monetary values are decimal strings.
Inputs: since_transaction_id. Returns: object
get_account_summaryARead-only
Get a summary of the configured account (no order/trade/position lists).
Returns {"account": {...}, "lastTransactionID": "..."} with the
same summary fields as get_account — monetary values as decimal
strings in the home currency, marginRate as a decimal string
(e.g. "0.02" = 50:1 leverage), open-item counts, and RFC3339
timestamps. This is the lightest way to check balance, NAV, and margin
headroom.
Inputs: no named parameters. Returns: object
get_candlesARead-only
Fetch OHLC candles for an instrument.
Specify either count (most recent N candles) or an RFC3339
from_time/to_time range; count cannot be combined with both
range bounds. A single request returns at most 5000 candles — for
longer ranges, paginate by setting from_time to the exact time
of the last candle received (not past it, or one candle is silently
skipped) and include_first to false (note the excluded first
candle still counts against count, so a full follow-up page holds
one candle fewer).
Returns instrument, granularity and candles: each candle
has an RFC3339 time, volume (number of price ticks, an
integer), complete (false means the candle is still forming — skip
it for analysis), and o/h/l/c prices as decimal strings (flattened for
a single price component, nested under mid/bid/ask when
several components are requested).
Inputs: instrument (required), count, price, smooth, +4 more. Returns: object
get_latest_candlesARead-only
Get the most recent candle for each requested instrument/granularity.
Returns {"latest_candles": [...]} with one entry per specification:
instrument, granularity, and candles — each candle carries
time (RFC3339), complete (false means the candle is still
forming), volume (number of price ticks), and an o/h/l/
c object per requested price side (bid/mid/ask) with
prices as decimal strings.
Inputs: candle_specifications (required). Returns: object
get_orderARead-only
Get a single order by ID or client-assigned ID.
Returns {"order": {...}, "lastTransactionID": "..."} with the same
fields as list_orders entries: id, type, instrument,
units (signed decimal string), price (decimal string),
state (PENDING, FILLED, TRIGGERED, CANCELLED),
timeInForce, RFC3339 timestamps, and fill/cancel bookkeeping such
as tradeOpenedID or cancellingTransactionID when present.
Inputs: order_specifier (required). Returns: object
get_order_bookARead-only
Fetch the aggregate pending-order book for an instrument.
Snapshots are produced periodically, not per-tick. Returns time
(RFC3339), the snapshot price and bucketWidth (decimal
strings), and buckets trimmed to at most depth buckets on each
side of the current price. Each bucket has a price and
longCountPercent/shortCountPercent — the percentage of pending
long/short orders at that price, as decimal strings (e.g. "0.2543"
means 0.2543%).
Inputs: instrument (required), time, depth. Returns: object
get_positionARead-only
Get the account's position for one instrument (open or flat).
Returns {"position": {...}, "lastTransactionID": "..."}. The
position has instrument, lifetime realized pl,
unrealizedPL, marginUsed, financing (decimal strings in
the home currency), and long/short sides with units
(decimal string; negative on the short side, "0" when flat),
averagePrice (only while open), tradeIDs, pl, and
unrealizedPL. Requesting an instrument the account has never
traded fails with HTTP 404.
Inputs: instrument (required). Returns: object
get_position_bookARead-only
Fetch the aggregate open-position book for an instrument.
Same shape as the order book, but each bucket's
longCountPercent/shortCountPercent (decimal strings, e.g.
"0.2543" means 0.2543%) describe open positions held at that price
rather than pending orders. Returns time (RFC3339), the snapshot
price and bucketWidth (decimal strings), and buckets
trimmed to at most depth buckets on each side of the current price.
Inputs: instrument (required), time, depth. Returns: object
get_pricingARead-only
Get the current price for one or more instruments.
Returns {"time": ..., "prices": [...]} with one entry per requested
instrument: instrument, time (RFC3339 timestamp of the quote),
tradeable (false outside trading hours or when the market is
halted), bid and ask (best available prices, decimal strings;
null when that side has no liquidity), and spread (ask minus bid as
a number in price units; null when either side is missing).
Inputs: instruments (required). Returns: object
get_tradeARead-only
Get the details of a single trade on the configured account.
Returns {"trade": {...}, "lastTransactionID": "..."} where the
trade has id, instrument, price (entry fill, decimal
string), openTime (RFC3339), state (OPEN, CLOSED, or
CLOSE_WHEN_TRADEABLE), initialUnits / currentUnits
(decimal strings; positive = long, negative = short), realizedPL,
unrealizedPL, marginUsed, financing (decimal strings in
the home currency), any attached takeProfitOrder /
stopLossOrder / trailingStopLossOrder, and — for closed
trades — averageClosePrice and closeTime.
Inputs: trade_specifier (required). Returns: object
get_transactionARead-only
Get the details of a single transaction.
Returns {"transaction": {...}, "lastTransactionID": "..."}. Every
transaction has id, time (RFC3339), and type
(e.g. ORDER_FILL, MARKET_ORDER, ORDER_CANCEL,
DAILY_FINANCING, TRANSFER_FUNDS); the remaining fields depend
on the type. Monetary values (pl, financing, commission,
accountBalance, amount) and units/price are decimal
strings; units is signed (positive = long, negative = short).
Internal bookkeeping fields (request/batch IDs, conversion factors)
are dropped.
Inputs: transaction_id (required). Returns: object
get_transactions_rangeARead-only
Get the transactions in an inclusive ID range.
This is the endpoint that returns actual transactions — use it with
the ID ranges from list_transactions page links, or directly when
you know the IDs. Returns {"transactions": [...], "lastTransactionID": "..."}; each transaction carries id,
time (RFC3339), type, and its type-specific fields (see
get_transaction). Monetary values and units/price are
decimal strings; units is signed (positive = long, negative =
short). Keep ranges modest — the API serves at most 1000 transactions
per request.
Inputs: to_id (required), from_id (required), limit, transaction_types. Returns: object
list_account_instrumentsARead-only
List instruments tradeable on the configured account.
Returns {"instruments": [...]} where each entry has name
(e.g. EUR_USD), type (CURRENCY, CFD, or METAL),
displayName, pipLocation (power-of-ten exponent of one pip:
-4 means a pip is 0.0001), displayPrecision (the number of
decimal places order prices must be formatted to — use it for the
price of LIMIT/STOP orders or the API rejects them with a
PRICE_PRECISION error), tradeUnitsPrecision (decimal places
allowed in order units), minimumTradeSize (decimal string),
marginRate (decimal string; the margin required per unit, e.g.
"0.05" = 20:1 leverage), and maximumOrderUnits (decimal
string).
Inputs: limit, instruments. Returns: object
list_accountsARead-only
List the accounts authorized for the configured API token.
Returns {"accounts": [...]} where each entry has id (the
account identifier every other tool operates on, e.g.
001-001-1234567-001), tags (list of strings), and
mt4AccountID when the account is MT4-bridged.
Inputs: limit. Returns: object
list_open_positionsARead-only
List the account's open positions — instruments with at least one open trade.
Returns {"positions": [...], "lastTransactionID": "..."} with the
same shape as list_positions: per instrument, realized pl,
unrealizedPL, marginUsed, financing (decimal strings in
the home currency), and long/short sides carrying units
(decimal string; negative on the short side), averagePrice,
tradeIDs, pl, and unrealizedPL.
Inputs: limit. Returns: object
list_open_tradesARead-only
List every open trade on the configured account.
Returns {"trades": [...], "lastTransactionID": "..."} with the
same trade shape as list_trades: id, instrument, price
(entry fill, decimal string), openTime (RFC3339),
currentUnits (decimal string; positive = long, negative = short),
unrealizedPL and marginUsed (decimal strings in the home
currency), and any attached takeProfitOrder, stopLossOrder,
or trailingStopLossOrder.
Inputs: limit. Returns: object
list_ordersARead-only
List orders on the configured account, most recent first.
Returns {"orders": [...], "lastTransactionID": "..."}. Each order
carries id, type (e.g. MARKET, LIMIT, STOP,
MARKET_IF_TOUCHED, TAKE_PROFIT, STOP_LOSS,
TRAILING_STOP_LOSS), instrument, units (signed decimal
string: positive = long, negative = short), price (decimal
string), state (PENDING, FILLED, TRIGGERED, or
CANCELLED), timeInForce, createTime (RFC3339), and — where
applicable — fill/cancel bookkeeping and attached
takeProfitOnFill/stopLossOnFill/trailingStopLossOnFill
details.
Inputs: limit, state, before_id, instrument. Returns: object
list_pending_ordersARead-only
List every pending (not yet filled or cancelled) order on the account.
Returns {"orders": [...], "lastTransactionID": "..."} with the
same per-order fields as list_orders: id, type,
instrument, units (signed decimal string), price (decimal
string), timeInForce, createTime (RFC3339), and any attached
on-fill details.
Inputs: limit. Returns: object
list_positionsARead-only
List every position the account has ever held, one per instrument.
Includes flat positions kept for their lifetime P/L; use
list_open_positions for current exposure only. Returns
{"positions": [...], "lastTransactionID": "..."} where each
position has instrument, lifetime realized pl,
unrealizedPL, marginUsed, financing (all decimal strings
in the account's home currency), and a long and short side.
Each side has units (decimal string; positive on the long side,
negative on the short side, "0" when flat), averagePrice
(only while open), tradeIDs (the open trades composing the side),
pl, and unrealizedPL.
Inputs: limit. Returns: object
list_tradesARead-only
List trades on the configured account, most recent first.
Returns {"trades": [...], "lastTransactionID": "..."}. Each trade
has id, instrument, price (entry fill, decimal string),
openTime (RFC3339), state, initialUnits and
currentUnits (decimal strings whose sign gives direction:
positive = long, negative = short), realizedPL, unrealizedPL,
marginUsed (decimal strings in the account's home currency), and —
when attached — the dependent orders takeProfitOrder,
stopLossOrder, and trailingStopLossOrder (each with id and
price or distance). Closed trades additionally carry
averageClosePrice and closeTime.
Inputs: limit, state, before_id, instrument. Returns: object
list_transactionsARead-only
List the account's transaction pages for a time range.
Note the API quirk: this endpoint returns page links, not the
transactions themselves. The response is {"from": ..., "to": ..., "pageSize": ..., "count": ..., "pages": [...], "lastTransactionID": "..."} where count is the total number of
matching transactions and each entry in pages is a URL of the form
.../transactions/idrange?from=<id>&to=<id> covering at most
page_size transactions. To fetch the actual transactions, take the
from/to IDs out of a page URL and call
get_transactions_range. Timestamps are RFC3339.
Inputs: limit, to_time, from_time, page_size, +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 22 tools
Each tool targets a distinct resource or filtered view, such as list_orders vs list_pending_orders and list_trades vs list_open_trades. The only overlapping pair is get_account/get_account_summary, but the descriptions explicitly clarify the cost tradeoff. Overall, purposes are clearly delineated.
All tools follow a consistent list_X or get_X pattern with clear resource nouns (accounts, instruments, candles, orders, trades, positions, transactions). There are no mixed conventions or vague verbs.
At 22 tools, the server is on the heavy side, with several near-duplicate filter tools (list_open_*, list_pending_orders) and convenience wrappers (get_latest_candles) that could be folded into the base tools. Still, each tool maps to a clear endpoint and the count is within reason for a comprehensive trading data API.
The read side is exhaustive: accounts, instruments, market data, orders, trades, positions, and transactions are all covered. However, there are zero write or mutation tools—no way to create, modify, or cancel orders, close trades, or change account settings. This is a critical gap for a trading server and will cause agent failures when action is required.
Maintenance
Related MCP Connectors
Hosted MCP server for MT4 and MT5: read accounts, prices and candles, and place or close orders.
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
Connect any MCP client to MetaTrader 4/5 to read prices, manage positions, and place trades.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for the tastytrade brokerage API, providing tools for account management, market data, and order execution.18MIT
- AlicenseBqualityDmaintenanceA read-only-by-default MCP server for Interactive Brokers that exposes account, positions, PnL, market data, and trade history from a local TWS/IB Gateway session, with optional trading capabilities.15MIT
- FlicenseNot gradedqualityBmaintenanceIntegrates OANDA FX trading with technical analysis, economic news, stock/indices quotes, corporate financials, EDINET disclosures, and composite scoring into a unified MCP server.-
- AlicenseAqualityCmaintenanceMCP server for the Trading 212 public API, enabling account, portfolio, order, pie, and history access with read tools always available and trading tools opt-in.131MIT