Lightweight Model Context Protocol (MCP) server exposing read-only Interactive Brokers data (contracts, historical data, fundamentals, news, portfolio, account) via the asynchronous ibasync library and FastMCP. Ideal for feeding financial data into LLM workflows and autonomous agents while keeping trading disabled. This directory contains an MCP (Model Context Protocol) server that wraps the ibasy
Add this skill
npx mdskills install Hellek1/ib-mcp@Hellek1? Sign in with GitHub to claim this listing.Comprehensive read-only IB data access with excellent documentation and deployment flexibility
1# IB Async MCP Server23[](https://github.com/Hellek1/ib-mcp/actions/workflows/ci.yml)45Lightweight Model Context Protocol (MCP) server exposing read-only Interactive Brokers data (contracts, historical data, fundamentals, news, portfolio, account) via the asynchronous [`ib_async`](https://ib-api-reloaded.github.io/ib_async/) library and [`FastMCP`](https://github.com/modelcontextprotocol/fastmcp). Ideal for feeding financial data into LLM workflows and autonomous agents while keeping trading disabled.67## Overview89This directory contains an MCP (Model Context Protocol) server that wraps the ib_async library to allow LLMs to interact with Interactive Brokers data.1011## Features1213The MCP server provides the following tools for LLM interaction:1415### 1. Contract Lookup and Conversion16- **lookup_contract**: Look up contract details by ticker symbol and optional exchange/currency17- **ticker_to_conid**: Convert ticker symbol to contract ID (conid)1819### 2. Market Data20- **get_historical_data**: Retrieve historical market data with configurable duration, bar size, and data type2122### 3. News23- **get_news**: Retrieve current news articles for a contract24- **get_historical_news**: Retrieve historical news articles within a date range2526### 4. Fundamental Data27- **get_fundamental_data**: Retrieve fundamental data including financial summaries, ownership, financial statements, and more2829### 5. Portfolio and Account Information30- **get_portfolio**: Retrieve portfolio positions and details31- **get_account_summary**: Retrieve account summary information32- **get_positions**: Retrieve current positions with contract metadata, including option expiry/strike/right/multiplier fields3334## Prerequisites35361. **Interactive Brokers Account**: You need an active IB account372. **IB Gateway or TWS**: Download and install either:38 - [IB Gateway (Stable)](https://www.interactivebrokers.com/en/trading/ibgateway-stable.php) - Recommended for API-only use39 - [IB Gateway (Latest)](https://www.interactivebrokers.com/en/trading/ibgateway-latest.php) - Latest features40 - [Trader Workstation (TWS)](https://www.interactivebrokers.com/en/trading/tws.php) - Full trading platform41423. **API Configuration**:43 - Enable API access in TWS/Gateway: `Configure → API → Settings` and check "Enable ActiveX and Socket Clients"44 - Set appropriate port (default: 7497 for TWS, 4001 for Gateway)45 - Add `127.0.0.1` to trusted IPs if connecting locally4647## Installation4849### From source (development)50```bash51git clone https://github.com/Hellek1/ib-mcp.git52cd ib-mcp53pip install poetry54poetry install55```5657## Usage5859### Running the MCP Server6061#### STDIO Mode (Default)6263The default mode runs as a spawnable MCP server communicating via standard input/output. This is ideal for integration with MCP clients like Claude Desktop.6465```bash66# Using default settings (TWS on localhost:7497)67poetry run ib-mcp-server6869# Custom IB Gateway connection70poetry run ib-mcp-server --host 127.0.0.1 --port 4001 --client-id 17172# Help with all options73poetry run ib-mcp-server --help74```7576#### HTTP Mode7778HTTP mode runs a persistent server that listens on a host and port, enabling multi-client access and network connectivity.7980```bash81# Local HTTP server82poetry run ib-mcp-server --transport http --http-host 127.0.0.1 --http-port 80008384# Listen on all interfaces (for Docker/remote access)85poetry run ib-mcp-server --transport http --http-host 0.0.0.0 --http-port 80008687# Using environment variables88IB_MCP_TRANSPORT=http IB_MCP_HTTP_HOST=127.0.0.1 IB_MCP_HTTP_PORT=8000 poetry run ib-mcp-server89```9091**Security Note**: HTTP mode binds to localhost (127.0.0.1) by default. For remote access, place behind a reverse proxy with proper authentication and use a protected network.9293### Command Line Options9495#### IB Connection96- `--host`: IB Gateway/TWS host (default: 127.0.0.1)97- `--port`: IB Gateway/TWS port (default: 7497 for TWS, use 4001 for Gateway)98- `--client-id`: Unique client ID for the connection (default: 1)99100#### Transport Configuration101- `--transport`: Transport protocol - `stdio` (default) or `http`102- `--http-host`: HTTP server host (default: 127.0.0.1)103- `--http-port`: HTTP server port (default: 8000)104105### Environment Variables106107You can also use environment variables instead of flags:108109#### IB Connection110- `IB_HOST`111- `IB_PORT`112- `IB_CLIENT_ID`113114#### Transport115- `IB_MCP_TRANSPORT`116- `IB_MCP_HTTP_HOST`117- `IB_MCP_HTTP_PORT`118119Flags override environment variables if both are provided.120121### When to Use STDIO vs HTTP122123| Use Case | STDIO | HTTP |124|----------|-------|------|125| Claude Desktop integration | ✅ Recommended | ❌ Not supported |126| Local single-client usage | ✅ Simple setup | ⚠️ Overkill |127| Multi-client access | ❌ Not possible | ✅ Supported |128| Remote/network access | ❌ Not possible | ✅ Supported |129| Docker deployment | ✅ Simple | ✅ More flexible |130| Production usage | ✅ Secure by default | ⚠️ Needs auth/proxy |131132## Docker133134### Build135136```bash137docker build -t ib-mcp .138```139140### Run (connect to TWS running on host)141142#### STDIO Mode (Default)143144On macOS/Windows Docker Desktop you can reach host via `host.docker.internal` (already the default):145146```bash147docker run --rm -it \148 -e IB_HOST=host.docker.internal \149 -e IB_PORT=7497 \150 -e IB_CLIENT_ID=1 \151 ghcr.io/hellek1/ib-mcp152```153154On Linux you may need to add `--add-host host.docker.internal:host-gateway` and ensure the TWS/Gateway port is accessible:155156```bash157docker run --rm -it \158 --add-host host.docker.internal:host-gateway \159 -e IB_HOST=host.docker.internal \160 -e IB_PORT=7497 \161 ghcr.io/hellek1/ib-mcp162```163164Override arguments directly if preferred:165166```bash167docker run --rm -it ghcr.io/hellek1/ib-mcp --host host.docker.internal --port 4001 --client-id 2168```169170#### HTTP Mode171172Run as an HTTP server for multi-client or remote access:173174```bash175# Local access176docker run --rm -it -p 8000:8000 \177 -e IB_HOST=host.docker.internal \178 -e IB_PORT=7497 \179 -e IB_MCP_TRANSPORT=http \180 -e IB_MCP_HTTP_HOST=0.0.0.0 \181 -e IB_MCP_HTTP_PORT=8000 \182 ghcr.io/hellek1/ib-mcp183184# Or using command line arguments185docker run --rm -it -p 8000:8000 \186 ghcr.io/hellek1/ib-mcp \187 --host host.docker.internal --port 7497 \188 --transport http --http-host 0.0.0.0 --http-port 8000189```190191The HTTP server will be available at `http://localhost:8000/mcp/`.192193194### MCP Client Integration195196#### STDIO Mode197198The server communicates via stdio using the MCP protocol. It can be integrated with MCP-compatible tools and LLM applications.199200Example MCP client configuration (e.g. Claude Desktop) using Docker:201```json202{203 "mcpServers": {204 "ib-async": {205 "command": "docker",206 "args": [207 "run",208 "--rm",209 "--add-host","host.docker.internal:host-gateway",210 "-e","IB_HOST=host.docker.internal",211 "-e","IB_PORT=7497",212 "-e","IB_CLIENT_ID=1",213 "ghcr.io/hellek1/ib-mcp:latest"214 ]215 }216 }217}218```219220Notes:2211. Remove the `--add-host` line on macOS/Windows Docker Desktop (it's only needed on Linux).222223#### HTTP Mode224225For HTTP mode, connect to the server at `http://localhost:8000/mcp/` using any MCP-compatible HTTP client.226227## Available Tools228229### Contract Lookup230```231lookup_contract(symbol, sec_type="STK", exchange="SMART", currency="USD")232ticker_to_conid(symbol, sec_type="STK", exchange="SMART", currency="USD")233```234235### Market Data236```237get_historical_data(symbol, duration="1 M", bar_size="1 day", data_type="TRADES", exchange="SMART", currency="USD")238```239240### News241```242get_news(symbol, provider_codes="", exchange="SMART", currency="USD")243get_historical_news(symbol, start_date, end_date, provider_codes="", max_count=10, exchange="SMART", currency="USD")244```245246### Fundamentals247```248get_fundamental_data(symbol, report_type="ReportsFinSummary", exchange="SMART", currency="USD")249```250251Available report types:252- `ReportsFinSummary`: Financial summary253- `ReportsOwnership`: Ownership information254- `ReportsFinStatements`: Financial statements255- `RESC`: Research reports256- `CalendarReport`: Calendar events257258### Portfolio & Account259```260get_portfolio(account="")261get_account_summary(account="")262get_positions(account="")263```264265`get_positions` returns a markdown table with account, symbol, security type,266position, average cost, currency, exchange, local symbol, trading class, and267contract ID. Option positions also include expiry, strike, right, and multiplier.268269## Example Usage270271Once connected to an LLM through MCP, you can ask questions like:272273- "Look up the contract details for AAPL"274- "Get the last month of daily historical data for TSLA"275- "What are the recent news articles for Microsoft?"276- "Show me the financial summary for Google"277- "What positions do I currently have in my portfolio?"278279## Data Formats280281### XML to Markdown Conversion282283The server automatically converts XML-formatted fundamental data to markdown for better readability in LLM interactions.284285### Error Handling286287The server includes comprehensive error handling and will provide meaningful error messages when:288- IB connection fails289- Invalid symbols are requested290- Market data is not available291- Authentication issues occur292293## Troubleshooting294295### Connection Issues2962971. **"Cannot connect to Interactive Brokers"**298 - Ensure TWS/Gateway is running299 - Check that API is enabled in settings300 - Verify port numbers match (7497 for TWS, 4001 for Gateway)301 - Check firewall settings3023032. **"No contract found"**304 - Verify symbol spelling305 - Try different exchanges (NYSE, NASDAQ vs SMART)306 - Check if security type is correct3073083. **"No market data"**309 - Ensure you have appropriate market data subscriptions310 - Check if markets are open for real-time data311 - Try delayed data mode if real-time is not available312313### Performance Tips3143151. Use specific exchanges when possible instead of "SMART" routing3162. Limit historical data requests to reasonable time ranges3173. Cache contract IDs for frequently accessed symbols318319## Security Considerations320321- The MCP server operates in read-only mode - no order placement capabilities322- Credentials are handled by the IB Gateway/TWS application323- The server only accesses data you have permission to view in your IB account324325## Contributing3263271. Fork & branch: `feat/xyz`3282. Install dev deps: `poetry install`3293. Activate pre-commit: `pre-commit install`3304. Run tests: `poetry run pytest -q`3315. Open a PR with a concise description.332333### Release (maintainers)334```bash335poetry version patch # or minor / major336poetry build337poetry publish --username __token__ --password <pypi-token>338git tag v$(poetry version -s)339git push --tags340```341342## Support & References343344- IB API functionality: [ib_async docs](https://ib-api-reloaded.github.io/ib_async/)345- MCP protocol: [MCP spec](https://spec.modelcontextprotocol.io/)346- Interactive Brokers: [IB API docs](https://ibkrcampus.com/ibkr-api-page/twsapi-doc/)347348---349350Licensed under the BSD 3-Clause License. Contributions welcome.351
Full transparency — inspect the skill content before installing.