@claudium/solana-mcp-server/README.md

MCP server for Solana blockchain interaction via Solscan Pro API

# Solana MCP Server

A comprehensive MCP (Model Context Protocol) server for interacting with the Solana blockchain through natural language. Powered by Solscan Pro API v2.0 with support for multiple data providers.

## Features

- **🚀 Comprehensive Blockchain Data**: Access token prices, wallet portfolios, DeFi activities, and more
- **📊 Solscan Pro API Integration**: Professional-grade data with high reliability
- **🔄 Multiple Data Providers**: Fallback support with DexScreener and Jupiter
- **⚡ Smart Caching**: Reduces API calls and improves response time
- **🛡️ Error Handling**: Graceful error handling with user-friendly messages
- **🧮 Trading Tools**: Built-in calculator for profit/loss, position sizing, etc.
- **🔥 NPM Package**: Easy installation via NPM registry

## Installation

### Prerequisites
- Python 3.8 or higher
- Node.js 14 or higher (for NPM installation)
- Solscan Pro API key (get one at https://pro-api.solscan.io/)

### Install via NPM (Recommended)

```bash
npx @claudium/solana-mcp-server@latest
```

### Install from Source

1. **Clone the repository**
```bash
git clone https://github.com/yourusername/solana-mcp-server.git
cd solana-mcp-server
```

2. **Install dependencies**
```bash
pip install -e .
```

3. **Configure API key**
```bash
cp .env.example .env
# Edit .env and add your SOLANA_API_KEY
```

4. **Add to Claude Desktop**

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": {
    "solana": {
      "command": "python",
      "args": ["/path/to/solana-mcp-server/server.py"],
      "env": {
        "SOLANA_API_KEY": "your_solscan_api_key_here"
      }
    }
  }
}
```

5. **Restart Claude Desktop**

## Available Tools

### 🪙 Token Operations

#### Get Token Info
Get comprehensive token data including price, market cap, holders, and liquidity.
```
"What's the price of USDC?"
"Get info for token EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
```

#### Get Token Prices
Get current prices for single or multiple tokens.
```
"Get price for [token_address]"
"Get prices for multiple tokens: [address1, address2, address3]"
```

#### Find Trending Tokens
Discover trending and popular tokens on Solana.
```
"Show me trending tokens on Solana"
"What are the top gaining tokens today?"
```

### 👛 Wallet/Account Operations

#### Get Wallet Portfolio
Complete portfolio analysis with token balances and values.
```
"Show portfolio for wallet [address]"
"What tokens does [wallet_address] hold?"
```

#### Get Wallet Transactions
View transaction history for any wallet.
```
"Show recent transactions for [wallet]"
"Get transaction history for [address]"
```

#### Get DeFi Activities
Track DeFi positions and activities.
```
"Show DeFi activities for [wallet]"
"What yield farms is [address] in?"
```

### 🧮 Trading Calculator

Perform various trading calculations:
- **Profit/Loss**: Calculate P&L with fees
- **Position Sizing**: Risk management calculations
- **Price Targets**: Calculate multiplier targets
- **Price Impact**: Estimate slippage

```
"Calculate profit if I buy at 0.01 and sell at 0.05 with 1000 tokens"
"What's the position size with $10000 capital and 2% risk?"
```

## API Key Configuration

The server requires a Solscan Pro API key. You can provide it in several ways:

1. **Environment Variable** (Recommended for development)
```bash
export SOLANA_API_KEY=your_key_here
```

2. **In .env file** (Recommended for persistent setup)
```
SOLANA_API_KEY=your_key_here
```

3. **In Claude config** (Recommended for Claude Desktop)
```json
"env": {
  "SOLANA_API_KEY": "your_key_here"
}
```

## Project Structure

```
solana-mcp-server/
├── server.py           # Main MCP server
├── providers/          # Data provider integrations
│   ├── solscan/       # Solscan Pro API client
│   ├── dexscreener.py # DexScreener integration
│   └── jupiter.py     # Jupiter aggregator
├── tools/             # MCP tool implementations
│   ├── token/         # Token-related tools
│   ├── account/       # Wallet/account tools
│   ├── defi/          # DeFi analytics
│   └── market/        # Market data tools
└── utils/             # Utility functions
    ├── cache.py       # Caching system
    └── formatter.py   # Response formatting
```

## Development

### Running Tests
```bash
python -m pytest tests/
```

### Adding New Tools
1. Create a new file in `tools/` directory
2. Inherit from `BaseTool` class
3. Implement `name`, `description`, and `execute` methods
4. Register in `server.py`

### Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

## Error Handling

The server includes comprehensive error handling:
- API failures gracefully fallback to cached data
- User-friendly error messages
- Automatic retries for transient failures
- Rate limiting protection

## Caching Strategy

- Token prices: 30 seconds TTL
- Account data: 60 seconds TTL
- Trending tokens: 5 minutes TTL
- Historical data: 10 minutes TTL

## License

MIT License - see LICENSE file for details

## Support

- **Issues**: [GitHub Issues](https://github.com/yourusername/solana-mcp-server/issues)
- **Documentation**: [API Docs](https://pro-api.solscan.io/pro-api-docs/v2.0/reference)
- **Get API Key**: [Solscan Pro](https://pro-api.solscan.io/)

## Disclaimer

This tool requires a Solscan Pro API key for full functionality. Some features may be limited without proper API access. Always verify critical financial data from multiple sources.