iol-mcp

An unofficial Model Context Protocol (MCP) server for the InvertirOnline (IOL) REST API, the Argentine retail broker.

It lets AI agents such as Claude Code read your portfolio and account statement, fetch quotes and historical series, check MEP dollar rates, browse mutual funds (FCIs), and, only if you explicitly enable it, place and cancel orders.

Disclaimer

• This project is not affiliated with, endorsed by, or supported by InvertirOnline or any of its companies. "InvertirOnline" is a trademark of its owner.

• Use at your own risk. Software that can place orders with real money can lose real money. The authors accept no liability for any loss, including losses caused by bugs, API changes, or mistakes made by an AI agent. Nothing here is financial advice.

• Trading is disabled by default. Tools that buy, sell, cancel, subscribe or redeem are not even registered unless you set ENABLE_TRADING=true. Leave it off unless you understand what you are enabling, and consider using it only with an agent that asks you to confirm each action.

• Your IOL credentials are used to log in to the IOL API from the machine running this server. The server has no authentication of its own, so keep it on a machine and network you trust.

Related MCP server: upstox-mcp-server

Quick start

You need an InvertirOnline account with API access and either Docker or Node.js 24+.

1. Configure credentials

cp .env.example .env
# edit .env and set IOL_USERNAME and IOL_PASSWORD

See Configuration for all variables.

2. Run the server

Docker, prebuilt image (published by CI to GitHub Container Registry):

docker run -d --name iol-mcp --restart unless-stopped \
  --env-file .env -p 127.0.0.1:7577:7577 \
  ghcr.io/ejgonzalez90/iol-mcp:latest

Docker Compose, built locally:

docker compose up -d

Node.js, from source (no build step):

npm ci
npm run dev

The Node.js options read credentials from the process environment, not from .env; for example node --env-file=.env dist/index.js after npm run build, or export the variables in your shell.

The server listens on http://0.0.0.0:7577/mcp using the MCP Streamable HTTP transport. The examples publish it on 127.0.0.1 only, because the server has no authentication of its own; drop the 127.0.0.1: prefix only if you put it behind something that does.

3. Connect a client

Claude Code:

claude mcp add --transport http iol-mcp http://localhost:7577/mcp

Any other MCP client that supports Streamable HTTP (check your client's documentation for the exact config file and key names):

{
  "mcpServers": {
    "iol-mcp": {
      "type": "http",
      "url": "http://localhost:7577/mcp"
    }
  }
}

Configuration

* The server logs in lazily on the first API call using these variables and renews the short-lived bearer token automatically. If they are unset you can instead call the authenticate tool with explicit credentials.

On startup the server logs one line stating whether trading is enabled and how many trading tools were registered or skipped. Credentials are never logged; only set/MISSING is shown.

Tools

34 tools in total: 26 read-only and 8 that require ENABLE_TRADING=true.

Authentication

Account (read-only)

Quotations (read-only)

Securities (read-only)

Mutual funds, FCI (read-only)

MEP dollar rates (read-only)

Simplified operations (read-only)

Trading (requires ENABLE_TRADING=true)

These tools are not registered unless ENABLE_TRADING=true.

Development

npm ci
npm run dev        # run from source with tsx (no build)
npm run lint       # eslint
npm run build      # tsc -> dist/
npm test           # vitest; all tests mock fetch and never touch the network

Hot reload in Docker (mounts src/, restarts on save):

docker compose -f docker-compose.dev.yml up --build

Build the production image locally:

docker build --target runtime -t iol-mcp:latest .

When NODE_ENV is not production, GET /debug returns server health, uptime, and the active session count (credentials are reported only as set/MISSING). The production image sets NODE_ENV=production, which disables it.

To add a tool, register it with server.registerTool(...) in src/tools/ and make all HTTP calls through apiRequest() in src/client.ts. A tool that moves money or changes broker state must go in src/tools/trading.ts and be added to TRADING_TOOL_NAMES so the ENABLE_TRADING guard covers it.

License

MIT © 2026 ejgonzalez90