Crypto Portfolio MCP Server

A comprehensive read-only cryptocurrency portfolio management server built on the Model Context Protocol (MCP). Supports Binance, Coinbase, and Kraken exchanges with 18+ analytics tools for portfolio tracking, risk assessment, and market intelligence.

Overview

This MCP server provides real-time cryptocurrency portfolio analytics through Claude Desktop or any MCP-compatible client. It offers read-only access to your exchange accounts, ensuring your funds remain secure while providing deep insights into your holdings.

Key Features

• Multi-exchange portfolio aggregation (Binance, Coinbase, Kraken)
• Real-time price tracking and alerts
• Risk and diversification analysis
• Market intelligence and sentiment indicators
• Arbitrage opportunity detection
• Portfolio performance metrics

Quick Start

Prerequisites

• Python 3.10 or higher
• API keys from supported exchanges (read-only permissions only)
• Claude Desktop (optional, for AI-powered queries)

Installation

1. Clone the repository:

git clone https://github.com/lev-corrupted/CryptoPortfolioMCPServer.git
cd CryptoPortfolioMCPServer

2. Run the setup script:

chmod +x setup.sh
./setup.sh

3. Configure API credentials:

cp .env.example .env
# Edit .env with your exchange API keys

4. Test the configuration:

source venv/bin/activate
python test_config.py

Claude Desktop Configuration

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "crypto-portfolio": {
      "command": "/absolute/path/to/CryptoPortfolioMCPServer/venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/absolute/path/to/CryptoPortfolioMCPServer"
    }
  }
}

Replace /absolute/path/to/ with your actual installation path.

API Key Setup

IMPORTANT: Read-Only Permissions Only

Create API keys with read/view permissions only. Never enable trading or withdrawal permissions.

Binance

1. Log in to Binance and navigate to API Management
2. Create a new API key with only "Read" permissions
3. Copy the API Key and Secret to your .env file

Coinbase

1. Log in to Coinbase and go to Settings > API
2. Create a new API key with only "wallet:accounts:read" and "wallet:transactions:read"
3. Copy credentials to .env

Kraken

1. Log in to Kraken and go to Settings > API
2. Generate a new key with only "Query Funds" and "Query Open Orders & Trades"
3. Copy credentials to .env

Available Tools

The server provides 18 MCP tools across 7 categories:

Portfolio Management (5 tools)

• get_total_portfolio_value - Aggregate portfolio value across all exchanges
• get_all_balances - Detailed balance breakdown with USD values
• get_portfolio_allocation - Asset allocation percentages
• get_current_prices - Real-time cryptocurrency prices
• calculate_portfolio_pnl - Profit/loss calculations

Analytics (2 tools)

• get_biggest_movers - Top gaining and losing assets
• get_portfolio_performance - Historical performance metrics

Price Alerts (2 tools)

• check_price_alert - Single price condition monitoring
• check_multiple_alerts - Batch alert checking

Risk Management (3 tools)

• get_diversification_score - Portfolio diversification rating (1-10)
• get_volatility_risk - Risk assessment based on asset volatility
• get_stablecoin_ratio - Percentage in stablecoins

Market Intelligence (3 tools)

• check_arbitrage_opportunities - Cross-exchange price differences
• check_liquidity - Trading volume and liquidity analysis
• get_fear_greed_index - Crypto market sentiment indicator

Portfolio Insights (2 tools)

• detect_dust - Identify small-value holdings
• get_exchange_distribution - Portfolio distribution across exchanges

Practical Tools (1 tool)

• calculate_withdrawal_fees - Estimate transfer costs

Usage Examples

With Claude Desktop

After configuration, ask Claude natural language questions:

"What is my total portfolio value?"
"Show me my portfolio allocation"
"What are the biggest movers in my portfolio today?"
"Is Bitcoin above $50,000?"
"What is my diversification score?"
"Are there any arbitrage opportunities?"
"What is the current crypto fear and greed index?"

Architecture

CryptoPortfolioMCPServer/
├── src/
│   ├── server.py              # Main MCP server
│   ├── exchanges/             # Exchange client implementations
│   │   ├── base_exchange.py
│   │   ├── binance_client.py
│   │   ├── coinbase_client.py
│   │   └── kraken_client.py
│   ├── analytics/             # Analytics engines
│   │   ├── portfolio.py
│   │   ├── risk.py
│   │   └── market.py
│   └── utils/                 # Utilities
│       ├── config.py
│       └── helpers.py
├── .github/                   # GitHub templates
├── requirements.txt
├── setup.sh
├── test_config.py
└── .env.example

Technical Details

• Exchange API Integration: CCXT library for unified exchange access
• Caching: In-memory with configurable TTL (30s prices, 60s balances)
• Rate Limiting: Per-exchange limits (Binance: 15/s, Coinbase: 8/s, Kraken: 1/s)
• Error Handling: Automatic retry with exponential backoff (3 attempts)
• Security: Read-only operations, no trading or withdrawal capabilities

Configuration

Environment variables in .env:

# Exchange API credentials
BINANCE_API_KEY=your_binance_api_key
BINANCE_API_SECRET=your_binance_secret

COINBASE_API_KEY=your_coinbase_api_key
COINBASE_API_SECRET=your_coinbase_secret

KRAKEN_API_KEY=your_kraken_api_key
KRAKEN_API_SECRET=your_kraken_secret

# Optional settings
MOCK_MODE=false
PRICE_CACHE_DURATION=30
BALANCE_CACHE_DURATION=60

Troubleshooting

"No exchanges initialized"

Check that API keys are correctly set in .env file.

"Failed to initialize [Exchange]"

Verify API key permissions are set to read-only and credentials are correct.

Rate Limiting Errors

The server implements automatic rate limiting and retry logic.

Security

Important Security Practices:

1. Use read-only API keys exclusively
2. Never commit .env file to version control
3. Enable IP whitelisting on exchange API keys (recommended)
4. Rotate API keys periodically
5. Keep dependencies updated

This server cannot execute trades or withdrawals - it only reads portfolio data.

Contributing

See CONTRIBUTING.md for guidelines.

Contributions must:

• Follow existing code patterns
• Include documentation
• Maintain security best practices
• Never add trading/withdrawal functionality

License

MIT License - See LICENSE file for details.

Disclaimer

This software is for informational purposes only and does not constitute financial advice. Users are solely responsible for their investment decisions. The server operates in read-only mode and cannot execute trades or transfers.

Support

For issues or questions:

1. Check the troubleshooting section above
2. Review CONTRIBUTING.md
3. Check server logs in logs/crypto_mcp.log
4. Open an issue on GitHub

Built With

• CCXT - Cryptocurrency exchange trading library
• MCP Python SDK - Model Context Protocol
• Python 3.10+