akapal-mcp-portfolio

MCP server that exposes portfolio and brokerage data through Model Context Protocol tools over streamable HTTP transport.

Data is currently backed by mock brokerage data (StaticBrokerageService). Live quotes are attempted first via LiveMarketService (yfinance) with automatic fallback to mock data when the live source is unavailable. A real E*TRADE API connection is planned as the next step.

Features

• Streamable HTTP transport on port 8080 (configurable via PORT), binds to 0.0.0.0; MCP endpoint served at /mcp

• Mock brokerage data — balances, holdings, sector allocation, quotes, market summary, FAQ

• Live quote fallback — real-time quotes when available, mock otherwise

• Order preview — estimates the portfolio impact of a buy/sell order without placing it

• Concentration analysis — flags positions exceeding a 15% threshold

• Keyword search — queries brokerage data and lists public financial sources (Yahoo, Bloomberg, Reuters, Morningstar, SEC)

Related MCP server: Open Stocks MCP

Requirements

• Python 3.11+

Installation

pip install .

For development:

pip install -e .

Usage

Start the server:

python -m app

Or via Docker:

docker build -t akapal-mcp-portfolio .
docker run -p 8080:8080 akapal-mcp-portfolio

The server listens on http://0.0.0.0:8080 and serves the MCP endpoint at /mcp. Point an MCP client (e.g. Claude Desktop, IDE MCP config, Google Agent Registry) at it to discover and call the tools.

Configuration

Google Agent Registry

The server is registered in Google Cloud Agent Registry so agents can discover and call its tools. Registration uploads toolspec.json (the MCP tool specification for the 9 tools) and points at the public Cloud Run endpoint.

To register or update the entry:

gcloud agent-registry services create mcp-portfolio \
    --project="$PROJECT_ID" \
    --location=us-east1 \
    --display-name="ETrade Portfolio MCP" \
    --mcp-server-spec-type=tool-spec \
    --mcp-server-spec-content=@toolspec.json \
    --interfaces=url="https://mcp-portfolio-492310803820.us-east1.run.app/mcp",protocolBinding=jsonrpc

deploy.sh runs this automatically after deploying to Cloud Run. Keep toolspec.json in sync with the tools declared in app.py; it must stay under the 10KB specification limit.

Tools

Project Structure

├── app.py                     # FastMCP server, streamable HTTP transport, tool definitions
├── models/                    # Dataclasses for account, holdings, quote, market, etc.
├── services/
│   ├── static_brokerage_service.py   # Mock brokerage data
│   └── live_market_service.py        # Live quotes (yfinance) with fallback
└── toolspec.json              # MCP tool specification uploaded to Agent Registry

Roadmap

• Connect real E*TRADE API for live brokerage data

• Wire up live financial-news retrieval for the public sources in search_financial_info