# 🔐 Crypto MCP Server

**The first blockchain & cryptocurrency MCP server** - Connect AI agents to Ethereum, Solana, Bitcoin, and cryptocurrency markets.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-1.0-green)](https://modelcontextprotocol.io)

## 🚀 Features

- **Multi-Chain Support**: Ethereum, Solana, and Bitcoin
- **Wallet Balance Queries**: Check balances for any address
- **Transaction History**: Get detailed transaction data
- **Real-Time Prices**: Live cryptocurrency prices from CoinGecko
- **Gas Price Monitoring**: Track Ethereum gas prices
- **Whale Tracking**: Monitor large wallet movements
- **Token Information**: ERC-20 token balances and data
- **Market Data**: Top tokens, price history, and search

## 📦 Installation

### Prerequisites

- Node.js 18.0.0 or higher
- npm or yarn
- API keys (see [API Keys](#-api-keys) section)

### Quick Start

1. **Clone or download this repository**

```bash
git clone https://github.com/rex-automata/crypto-mcp-server.git
cd crypto-mcp-server
```

2. **Install dependencies**

```bash
npm install
```

3. **Configure environment variables**

```bash
cp .env.example .env
# Edit .env and add your API keys
```

4. **Build the project**

```bash
npm run build
```

5. **Test the server**

```bash
npm start
```

## 🔑 API Keys

### Required APIs (Free Tier)

#### Etherscan API
- **Get it at**: https://etherscan.io/apis
- **Free tier**: 5 calls/second, 100,000 calls/day
- **Add to `.env`**: `ETHERSCAN_API_KEY=your_key_here`

#### CoinGecko API
- **Get it at**: https://www.coingecko.com/en/api/pricing
- **Free tier**: Works without API key (50 calls/minute)
- **Pro tier**: Higher rate limits available
- **Add to `.env`**: `COINGECKO_API_KEY=your_key_here` (optional)

#### Solana RPC
- **Default**: Uses public endpoint (`https://api.mainnet-beta.solana.com`)
- **Free upgrades**: Alchemy (https://www.alchemy.com) or QuickNode (https://www.quicknode.com)
- **Add to `.env`**: `SOLANA_RPC_URL=your_rpc_url` (optional)

#### Blockchain.info (Bitcoin)
- **No API key required** for basic usage
- Higher limits available at https://www.blockchain.com/api

## 🛠️ Usage

### MCP Client Configuration

Add to your MCP client settings (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "crypto": {
      "command": "node",
      "args": ["/path/to/crypto-mcp-server/dist/index.js"],
      "env": {
        "ETHERSCAN_API_KEY": "your_key_here",
        "COINGECKO_API_KEY": "your_key_here",
        "SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com"
      }
    }
  }
}
```

### Available Tools

#### Ethereum Tools

- `get_eth_balance` - Get ETH balance for an address
- `get_eth_transactions` - Get transaction history
- `get_gas_price` - Get current gas prices
- `get_token_balance` - Get ERC-20 token balance

#### Solana Tools

- `get_sol_balance` - Get SOL balance for an address
- `get_sol_transactions` - Get transaction history

#### Bitcoin Tools

- `get_btc_balance` - Get BTC balance for an address
- `get_btc_transactions` - Get transaction history
- `get_btc_stats` - Get Bitcoin network statistics

#### Price Tools

- `get_token_price` - Get current price for a cryptocurrency
- `get_multiple_prices` - Get prices for multiple tokens
- `get_top_tokens` - Get top cryptocurrencies by market cap
- `search_token` - Search for a cryptocurrency
- `get_price_history` - Get historical price data

#### Whale Tracking Tools

- `is_whale_address` - Check if an address is a whale
- `get_whale_transactions` - Get large transactions for an address
- `get_known_whale_addresses` - Get list of known whale addresses

## 💡 Example Usage

```typescript
// Get Ethereum balance
{
  "tool": "get_eth_balance",
  "arguments": {
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
  }
}

// Get Bitcoin price
{
  "tool": "get_token_price",
  "arguments": {
    "coinId": "bitcoin"
  }
}

// Check if address is a whale
{
  "tool": "is_whale_address",
  "arguments": {
    "address": "0xBE0eB53F46cd790Cd13851d5EFf43D12404d33E8",
    "chain": "ethereum"
  }
}

// Get top 10 cryptocurrencies
{
  "tool": "get_top_tokens",
  "arguments": {
    "limit": 10
  }
}
```

## 📁 Project Structure

```
crypto-mcp-server/
├── index.ts                 # Main MCP server
├── tools/
│   ├── ethereum.ts         # Ethereum tools
│   ├── solana.ts           # Solana tools
│   ├── bitcoin.ts          # Bitcoin tools
│   ├── prices.ts           # Price tracking tools
│   └── whale.ts            # Whale tracking tools
├── package.json
├── tsconfig.json
├── .env.example
└── README.md
```

## 🚧 Roadmap

### Phase 1: Core Features (Current)
- ✅ Multi-chain balance queries
- ✅ Transaction history
- ✅ Price tracking
- ✅ Gas monitoring
- ✅ Basic whale tracking

### Phase 2: Premium Features (Planned)
- 🔲 Real-time transaction monitoring webhooks
- 🔲 Advanced whale alerts (Telegram/Discord notifications)
- 🔲 Portfolio tracking across chains
- 🔲 NFT balance and floor price tracking
- 🔲 DeFi protocol integration (Uniswap, Aave, etc.)
- 🔲 Custom alert conditions
- 🔲 Historical data export

### Phase 3: Enterprise Features
- 🔲 Multi-user support with API key management
- 🔲 Rate limiting and quota management
- 🔲 Advanced analytics and reporting
- 🔲 Custom RPC endpoints
- 🔲 White-label deployment options

## 💰 Monetization Strategy

1. **Freemium Model**
   - Free tier: Basic queries with public APIs
   - Pro tier ($9/month): Higher rate limits, more chains
   - Enterprise tier ($99/month): Custom features, dedicated support

2. **API Access**
   - Sell API access to the MCP server
   - Volume-based pricing

3. **Premium Features**
   - Real-time alerts: $5/month
   - Advanced whale tracking: $15/month
   - Portfolio analytics: $10/month

4. **Consulting/Custom Development**
   - Custom blockchain integrations
   - Private deployment

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🔗 Links

- **GitHub**: https://github.com/rex-automata/crypto-mcp-server
- **MCP Documentation**: https://modelcontextprotocol.io
- **Issues**: https://github.com/rex-automata/crypto-mcp-server/issues

## ⚠️ Disclaimer

This software is provided for informational purposes only. It does not constitute financial advice. Always do your own research before making any investment decisions.

## 📧 Contact

- GitHub: [@rex-automata](https://github.com/rex-automata)
- Issues: [GitHub Issues](https://github.com/rex-automata/crypto-mcp-server/issues)

---

**Built with ❤️ for the MCP community**