# 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:
```bash
git clone https://github.com/lev-corrupted/CryptoPortfolioMCPServer.git
cd CryptoPortfolioMCPServer
```

2. Run the setup script:
```bash
chmod +x setup.sh
./setup.sh
```

3. Configure API credentials:
```bash
cp .env.example .env
# Edit .env with your exchange API keys
```

4. Test the configuration:
```bash
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`

```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`:

```bash
# 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](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](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](CONTRIBUTING.md)
3. Check server logs in `logs/crypto_mcp.log`
4. Open an issue on GitHub

## Built With

- [CCXT](https://github.com/ccxt/ccxt) - Cryptocurrency exchange trading library
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - Model Context Protocol
- Python 3.10+