etoro-mcp

etoro-mcp

MCP server for the eToro public API: market data, balances,portfolio, trade history, watchlists, alerts, investor rankings, user statistics, social feeds,and — behind explicit opt-in gates — trading, watchlist/alert mutations, and social posting.Coverage is organised into toolsets; only the toolsets you select are registered, and writetools are not registered at all unless their gate is enabled — a client connected to the defaultconfiguration cannot see or call them.

Features

• Read-first by design — 62 read tools across eleven of the twelve toolsets (the socialtoolset is write-only); the 43 write tools exist only when their gate is set — 5 tradingtools behind ETORO_MCP_ENABLE_TRADING, the other 38 (watchlist, alert, social, andnotification mutations) behind ETORO_MCP_ENABLE_WRITES.
• Demo environment by default — trading tools call the demo endpoint group unlessETORO_ENV=real is set.
• Toolset selection — register only what you need via ETORO_MCP_TOOLSETS; unknown namesfail startup rather than serving a partial tool set.
• Trimmed responses — tools return the fields an investor acts on (prices, units, P&L,timestamps), not raw API dumps; list tools are bounded by a limit parameter or byexplicit range parameters (min_date/max_date/count) on the time-series tools.
• Credentials stay in the environment — keys travel only in the x-api-key/x-user-keyheaders, and error messages never echo header or credential values.
• Rate-limit aware — HTTP 429 responses are retried once, honouring Retry-After, re-sendingthe same x-request-id so a retried order cannot fill twice.

Toolsets

Select toolsets with ETORO_MCP_TOOLSETS (comma-separated; all selects every toolset).Without it, the trading core is registered:

Tools

Read tools (registered whenever their toolset is selected)

Trading write tools (registered only when ETORO_MCP_ENABLE_TRADING is set)

Other write tools (registered only when ETORO_MCP_ENABLE_WRITES 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/etoro-mcp etoro-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 API keys' privileges. The server thereforerefuses to bind a non-loopback --host unless --allow-remote is also passed; only usethat flag behind an authenticated reverse proxy or an otherwise-restricted network (such asthe 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": {
    "etoro": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/florinel-chis/etoro-mcp", "etoro-mcp"],
      "env": {
        "ETORO_API_KEY": "your-api-key",
        "ETORO_USER_KEY": "your-user-key",
        "ETORO_ENV": "demo"
      }
    }
  }
}

Or run the Docker image (build it first, see below):

{
  "mcpServers": {
    "etoro": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "ETORO_API_KEY", "-e", "ETORO_USER_KEY", "-e", "ETORO_ENV", "etoro-mcp"],
      "env": {
        "ETORO_API_KEY": "your-api-key",
        "ETORO_USER_KEY": "your-user-key",
        "ETORO_ENV": "demo"
      }
    }
  }
}

Docker

docker build -t etoro-mcp .

# stdio (for MCP client configs)
docker run -i --rm -e ETORO_API_KEY -e ETORO_USER_KEY etoro-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 ETORO_API_KEY -e ETORO_USER_KEY \
  etoro-mcp --transport http --host 0.0.0.0 --port 8000 --allow-remote

Safety

• Trading tools call the demo endpoint group unless ETORO_ENV=real is set. Keys areenvironment-bound, so a demo key against real (or vice versa) fails at the API rather thantrading the wrong account.
• Write tools are hidden behind two independent gates — ETORO_MCP_ENABLE_TRADING fororder/position writes and ETORO_MCP_ENABLE_WRITES for everything else (watchlists, alerts,notifications, social). Gated tools are never registered, not merely rejected, so MCP clientscannot 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 keys' privileges. The server refuses non-loopback binds unless--allow-remote is passed; only use that flag behind an authenticated proxy or anotherwise-restricted network (the stdio transport has no such exposure).
• upload_media reads local JPEG/PNG files and returns a public CDN URL for them — anextra privilege class beyond the API keys themselves. It is therefore triple-gated: thesocial toolset, ETORO_MCP_ENABLE_WRITES, and ETORO_MCP_UPLOAD_DIR must all be set,and it reads only inside that directory (paths and symlinks resolving outside it arerejected, file content must actually be JPEG/PNG, and the 8 MB limit is checked before thefile is read).
• create_order is not idempotent across calls: each call mints a fresh x-request-id,which is the order's idempotency key, so calling it twice places two orders. (The 429 retryre-sends the same id, so a rate-limited retry cannot double-fill.) Poll fill status withget_order before treating an order as filled — an accepted order can still be rejected.
• Candle history is capped at roughly 1000 bars per interval with no way to page furtherback; use a coarser interval (e.g. OneWeek) for deeper history.
• The API enforces per-group rate quotas (order execution 20 requests/60 s; market data120/60 s; portfolio and most other groups 60/60 s; eligibility and cost estimates 20/60 seach). Each tool's description names its quota; 429s are retried once, honouringRetry-After.
• Trading leveraged products is risky. Use at your own risk, and test everything against ademo 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 demo account lives at scripts/smoke.py.

License

MIT — see LICENSE.