IB Portfolio Tracker - MCP Server

An MCP (Model Context Protocol) server that connects Claude AI to your Interactive Brokers account for real-time portfolio tracking, financial news, and sentiment analysis.

What Can You Do?

Once set up, you can ask Claude things like:

• "What's my portfolio value?"
• "Show my positions with P&L"
• "Give me a full news analysis for NVDA" (combines IB + Finnhub + sentiment)
• "What's the sentiment around Tesla?"
• "Show historical data for SPY"
• "What news providers are available from IB?"

All responses come directly from your Interactive Brokers account, IB news feeds (Reuters, Dow Jones, etc.), and optionally Finnhub API.

Quick Start

Prerequisites

• macOS, Linux, or Windows
• Python 3.10+ installed
• Interactive Brokers account
• Claude Desktop or Claude Code (VS Code)

Step 1: Download IB Gateway

IB Gateway is a lightweight app that allows API access to your IBKR account.

1. Download from: https://www.interactivebrokers.com/en/trading/ibgateway-stable.php
2. Install and log in with your IBKR credentials
3. Configure API settings:
   • Go to Configure → Settings → API → Settings
   • Set Socket port to 4001
   • Check Read-Only API (recommended for safety)
4. Keep IB Gateway running whenever you want to use the portfolio features

Note: IBKR Desktop app does NOT support API connections. You need IB Gateway or TWS.

Step 2: Get a Finnhub API Key (Optional)

Finnhub provides additional news and social sentiment data. This is optional - IB native news works without it.

1. Sign up at: https://finnhub.io/register
2. Copy your API key from the dashboard
3. Free tier: 60 requests/minute (plenty for personal use)

Step 3: Install the MCP Server

# Clone or download this repository
git clone https://github.com/vinbg/ib-mcp-server.git
cd ib-mcp-server

# Run the setup script
# Mac/Linux:
chmod +x setup.sh
./setup.sh

# Windows:
setup.bat

The setup script will:

• Create a Python virtual environment
• Install all dependencies
• Guide you through configuration
• Test your connections

Step 4: Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ib-portfolio": {
      "command": "/FULL/PATH/TO/ib-mcp-server/.venv/bin/python",
      "args": ["-m", "ib_mcp.server"],
      "cwd": "/FULL/PATH/TO/ib-mcp-server"
    }
  }
}

Replace /FULL/PATH/TO/ with your actual path!

Then restart Claude Desktop (Cmd+Q, then reopen).

Optional: Add LunarCrush for Crypto Sentiment

LunarCrush provides social sentiment data for cryptocurrencies. To add it alongside this server:

1. Get an API key at: https://lunarcrush.com/developers
2. Add to your Claude Desktop config:

{
  "mcpServers": {
    "ib-portfolio": {
      "command": "/FULL/PATH/TO/ib-mcp-server/.venv/bin/python",
      "args": ["-m", "ib_mcp.server"],
      "cwd": "/FULL/PATH/TO/ib-mcp-server"
    },
    "LunarCrush": {
      "type": "http",
      "url": "https://lunarcrush.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_LUNARCRUSH_API_KEY"
      }
    }
  }
}

Now you can ask Claude about crypto social sentiment alongside your IBKR portfolio!

Available Tools (22 total)

Comprehensive News (RECOMMENDED)

Portfolio Tools (requires IB Gateway)

Market Data Tools (requires IB Gateway)

IB Native News Tools (requires IB Gateway)

Finnhub News & Sentiment Tools (requires Finnhub API)

Sentiment Analysis Tools

Utility Tools

Configuration

All settings are in the .env file:

# Interactive Brokers Connection
IB_HOST=127.0.0.1
IB_PORT=4001              # 4001=Gateway Paper, 4002=Gateway Live

# News API
FINNHUB_API_KEY=your_finnhub_key_here

# Sentiment Model
SENTIMENT_MODEL=vader     # "vader" (fast) or "finbert" (accurate, 500MB model)

# Logging
LOG_LEVEL=INFO

Port Reference

Security

This server is READ-ONLY by default:

• No order placement capabilities
• No account modification
• API keys stored locally in .env (never committed to git)
• Works with IB's "Read-Only API" setting

Your credentials never leave your machine. The MCP server runs locally and communicates only with:

• IB Gateway on localhost
• Finnhub API (for news)

Troubleshooting

"Cannot connect to IB Gateway"

1. Is IB Gateway running? Check your dock/taskbar
2. Correct port? Verify port in IB Gateway matches your .env
3. API enabled? In IB Gateway: Configure → Settings → API → Settings
4. Firewall? Ensure localhost connections aren't blocked

"Invalid API key" (Finnhub)

1. Check your key at https://finnhub.io/dashboard
2. Verify it's correctly copied to .env
3. Free tier limit: 60 requests/minute

"Tool not found" in Claude

1. Restart Claude Desktop completely (Cmd+Q)
2. Check the config file path is correct
3. Verify Python path: which python3 in terminal

Test the connection manually

cd ib-mcp-server
source .venv/bin/activate
python -c "
from ib_async import IB
import asyncio

async def test():
    ib = IB()
    await ib.connectAsync('127.0.0.1', 4001, clientId=99)
    print('Connected!')
    print('Accounts:', ib.managedAccounts())
    ib.disconnect()

asyncio.run(test())
"

Project Structure

ib-mcp-server/
├── setup.sh              # Mac/Linux setup script
├── setup.bat             # Windows setup script
├── pyproject.toml        # Python dependencies
├── .env.example          # Configuration template
├── .env                  # Your configuration (gitignored)
├── README.md             # This file
├── claude.md             # Claude Code documentation
└── src/ib_mcp/
    ├── server.py         # MCP server entry point
    ├── config.py         # Configuration management
    └── clients/
        ├── ib_client.py    # Interactive Brokers API
        ├── news_client.py  # Finnhub API
        └── sentiment.py    # Sentiment analysis

License

MIT License - feel free to use, modify, and share.

Disclaimer

This software is for informational purposes only. It does not constitute financial advice. Always verify information independently before making investment decisions. The authors are not responsible for any financial losses incurred through the use of this software.