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 arenot registered at all unless explicitly enabled — a client connected to the default configurationcannot 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 whenOANDA_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 areRFC3339, 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.

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 servestreamable HTTP at /mcp instead.

Warning: the HTTP endpoint has no authentication — anyone who can reach the port cancall every registered tool with your OANDA_API_TOKEN's privileges. Bind it to 127.0.0.1(never 0.0.0.0 on a reachable machine) and put an authenticated reverse proxy in front of itif it must be exposed beyond localhost.

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)
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

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 everyregistered tool — read balances and positions always, and place or close orders when tradingis enabled — using your API token's privileges. Keep it bound to 127.0.0.1 (the stdiotransport has no such exposure), or front it with an authenticated proxy if remote access isgenuinely needed.
• Order placement has a sharp edge: the API can accept an order and cancel it in the sameresponse — a FOK market order, for example, is cancelled for INSUFFICIENT_MARGIN orMARKET_HALTED. The order tools surface the cancel transaction so this is visible, but alwayscheck it before treating an order as filled.
• Trading leveraged products is risky. Use at your own risk, and test everything against apractice 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 thein-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.