Skip to main content
Glama
oanda-mcp

oanda-mcp

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_TRADING is 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 limit parameter.

  • 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 Authorization header, 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_accounts

List the accounts authorized for the configured API token

get_account

Full state of the configured account, trimmed to summary level

get_account_summary

Lightweight account summary: balance, NAV, margin headroom

list_account_instruments

Instruments tradeable on the account, with pip location, display precision, trade size limits, and margin rate

get_account_changes

Poll for order/trade/position changes since a transaction ID

get_candles

OHLC candles for an instrument at any granularity (S5 through monthly)

get_order_book

Aggregate pending-order book snapshot around the current price

get_position_book

Aggregate open-position book snapshot around the current price

get_pricing

Current bid/ask/spread for one or more instruments

get_latest_candles

Most recent candle per instrument/granularity specification

list_orders

Orders on the account, filterable by instrument and state

list_pending_orders

Every pending order on the account

get_order

A single order by ID or client-assigned ID

list_trades

Trades on the account, filterable by instrument and state

list_open_trades

Every open trade, with attached take-profit/stop-loss orders

get_trade

A single trade by ID or client-assigned ID

list_positions

Every position ever held, one per instrument, with lifetime P/L

list_open_positions

Positions with at least one open trade

get_position

The account's position for one instrument

list_transactions

Transaction page links for a time range (fetch pages with get_transactions_range)

get_transaction

A single transaction by ID

get_transactions_range

The transactions in an inclusive ID range

Write tools (registered only when OANDA_MCP_ENABLE_TRADING is set)

Tool

Description

configure_account

Change the account alias and/or account-wide margin rate

create_order

Create a MARKET/LIMIT/STOP/MARKET_IF_TOUCHED order with optional take profit / stop loss / trailing stop on fill

replace_order

Replace a pending order atomically (cancel + create)

cancel_order

Cancel a pending order

close_trade

Close an open trade, fully or partially, with a market order

set_trade_orders

Create, replace, or cancel a trade's take profit, stop loss, and trailing stop

close_position

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

OANDA_API_TOKEN

— (required)

Personal access token, sent as Authorization: Bearer ...

OANDA_ACCOUNT_ID

first authorized account

Account to operate on

OANDA_ENV

practice

practice (api-fxpractice) or live (api-fxtrade)

OANDA_MCP_ENABLE_TRADING

off

true/1/yes registers the write tools

Getting started

Run straight from the repository with uv:

uvx --from git+https://github.com/florinel-chis/oanda-mcp oanda-mcp

The 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 --host unless --allow-remote is 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-remote

Safety

  • The server talks to the practice environment unless OANDA_ENV=live is set.

  • Trading tools are hidden unless OANDA_MCP_ENABLE_TRADING is 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_MARGIN or MARKET_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 tools
get_accountA
Read-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_changesA
Read-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_summaryA
Read-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_candlesA
Read-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_candlesA
Read-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_orderA
Read-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_bookA
Read-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_positionA
Read-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_bookA
Read-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_pricingA
Read-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_tradeA
Read-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_transactionA
Read-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_rangeA
Read-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_instrumentsA
Read-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_accountsA
Read-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_positionsA
Read-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_tradesA
Read-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_ordersA
Read-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_ordersA
Read-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_positionsA
Read-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_tradesA
Read-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_transactionsA
Read-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

    A4/5.0

    Scored across 22 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness2/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server for the tastytrade brokerage API, providing tools for account management, market data, and order execution.
      18
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      A 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.
      15
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Integrates OANDA FX trading with technical analysis, economic news, stock/indices quotes, corporate financials, EDINET disclosures, and composite scoring into a unified MCP server.
      -
    • A
      license
      A
      quality
      C
      maintenance
      MCP 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.
      13
      1
      MIT