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
- Clone the repository:
git clone https://github.com/lev-corrupted/CryptoPortfolioMCPServer.git
cd CryptoPortfolioMCPServer
- Run the setup script:
chmod +x setup.sh
./setup.sh
- Configure API credentials:
cp .env.example .env
# Edit .env with your exchange API keys
- 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
- Log in to Binance and navigate to API Management
- Create a new API key with only "Read" permissions
- Copy the API Key and Secret to your
.envfile
Coinbase
- Log in to Coinbase and go to Settings > API
- Create a new API key with only "wallet:accounts:read" and "wallet:transactions:read"
- Copy credentials to
.env
Kraken
- Log in to Kraken and go to Settings > API
- Generate a new key with only "Query Funds" and "Query Open Orders & Trades"
- 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 exchangesget_all_balances- Detailed balance breakdown with USD valuesget_portfolio_allocation- Asset allocation percentagesget_current_prices- Real-time cryptocurrency pricescalculate_portfolio_pnl- Profit/loss calculations
Analytics (2 tools)
get_biggest_movers- Top gaining and losing assetsget_portfolio_performance- Historical performance metrics
Price Alerts (2 tools)
check_price_alert- Single price condition monitoringcheck_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 volatilityget_stablecoin_ratio- Percentage in stablecoins
Market Intelligence (3 tools)
check_arbitrage_opportunities- Cross-exchange price differencescheck_liquidity- Trading volume and liquidity analysisget_fear_greed_index- Crypto market sentiment indicator
Portfolio Insights (2 tools)
detect_dust- Identify small-value holdingsget_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:
- Use read-only API keys exclusively
- Never commit
.envfile to version control - Enable IP whitelisting on exchange API keys (recommended)
- Rotate API keys periodically
- 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:
- Check the troubleshooting section above
- Review CONTRIBUTING.md
- Check server logs in
logs/crypto_mcp.log - Open an issue on GitHub
Built With
- CCXT - Cryptocurrency exchange trading library
- MCP Python SDK - Model Context Protocol
- Python 3.10+