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: tastytrade-mcp

Tools

Read tools (always registered)

Write tools (registered only when OANDA_MCP_ENABLE_TRADING is set)

Configuration

All configuration comes from environment variables — no config files, no flags carrying secrets.

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.