ppi-mcp

An unofficial Model Context Protocol (MCP) server for the Portfolio Personal Inversiones (PPI) REST API, so AI agents such as Claude Code can read your portfolio, quotes and order history and, if you opt in, place orders.

Disclaimer. This project is not affiliated with, endorsed by, or supported by PPI. It is provided as-is, use it at your own risk. Trading involves financial risk, and an AI agent can make mistakes. Tools that move money or change state at the broker are disabled by default and only exist when you set ENABLE_TRADING=true. Read the code and try it against the PPI sandbox before pointing it at a real account.

Transport: Streamable HTTP, listening on http://0.0.0.0:7575/mcp inside the container. The examples publish it on 127.0.0.1 only, because the server has no authentication of its own.

Features

• 38 tools covering accounts, balances and positions, movements, market data, order history, pre-trade budgets, and reference data (instrument types, markets, settlements, holidays).

• Safe by default: 8 state-changing tools (orders, transfers, bank accounts, investor profile) are not registered unless ENABLE_TRADING=true.

• Automatic authentication: login and token refresh are handled for you.

• ppi_confirm_order re-reads the order after placing it and returns { confirmation, outcome }, because PPI can acknowledge an order and then cancel it server-side without it ever reaching the market.

• ppi_get_current_price and ppi_get_order_book attach a settlementWarning when PPI answers an A-48HS/A-72HS request with the A-24HS data (a settlement the instrument does not actually trade).

• Ships a catalog of 148 ETF/FCI-EXTERIOR instruments in src/data/etf-catalog.json.

Related MCP server: ibkr-mcp

Quick start

Create an env file first (see Configuration):

cp .env.example .env
# edit .env and fill in your PPI credentials

a) Docker, prebuilt image

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

b) Docker Compose, build locally

docker compose up -d

This builds the image from the Dockerfile, reads .env, restarts automatically, and publishes port 7575.

c) Node.js (development)

Requires Node.js 22+.

npm ci
npm run dev        # tsx --env-file=.env src/index.ts

Or build and run: npm run build && npm start (export the variables from .env yourself in this case).

Configuration

Getting PPI API credentials

The four PPI_* credentials come from PPI: the .env.example says to obtain them from your PPI client portal or through an API access request with PPI. This repository cannot tell you more than that; consult PPI's own documentation and support. Out of the box the server talks to the PPI sandbox; set PPI_BASE_URL to the base URL PPI gives you for your account to use real data.

Debug endpoint

When NODE_ENV is not production, GET /debug reports uptime, active sessions and whether each credential is set (never the values).

Connecting an MCP client

Claude Code

claude mcp add --transport http ppi-mcp http://localhost:7575/mcp

Other MCP clients

Any client that supports Streamable HTTP can point at the same URL. For clients configured with JSON, the shape is typically:

{
  "mcpServers": {
    "ppi-mcp": {
      "type": "http",
      "url": "http://localhost:7575/mcp"
    }
  }
}

The server has no authentication of its own: anyone who can reach port 7575 can use your PPI credentials. Keep it bound to localhost or a trusted network, never expose it to the internet.

Tools

Tools marked trading are only registered when ENABLE_TRADING=true. The budget/estimate tools execute nothing and are always available.

Account

Market data

Orders and transfers

Configuration (reference data)

At startup the server logs one line saying whether trading is enabled and how many trading tools were registered or skipped.

Development

npm ci
npm run dev           # run from source with .env
npm run build         # tsc -> dist/
npm run typecheck     # tsc --noEmit
npm run lint          # eslint
npm test              # vitest, fully offline (fetch is mocked)
npm run prettier:fix  # format src/**/*.ts

Docker targets: dev (hot reload with a mounted src/), builder, and runtime (the default final image). See CLAUDE.md for architecture notes and how to add a tool.

License

MIT © 2026 ejgonzalez90