ShreyashPatil530/crypto-mcp-server

🚀 Cryptocurrency MCP Server

Real-time & historical cryptocurrency market data with zero API keys required

Features: 🔴 Live Prices | 📈 Historical Data | 💾 Smart Cache | ✅ Fully Tested | 🚀 Production Ready

📌 Overview

A lightweight, production-ready MCP (Model Context Protocol) server for cryptocurrency market data retrieval. Fetch real-time prices and historical data for 18+ cryptocurrencies using the free CCXT library - no API key registration needed!

Perfect for: Trading bots, portfolio trackers, crypto dashboards, market analysis tools, and AI integrations.

✨ Key Features

• ✅ Real-time Prices - 18+ cryptocurrencies (BTC, ETH, XRP, ADA, SOL, DOGE, MATIC, LINK, LTC, BCH, DOT, AVAX, ARB, OP, SHIB, PEPE, NEAR, UNI)
• ✅ Historical Data - OHLCV candles for 1-365 days
• ✅ Smart Caching - 5-minute TTL reduces API calls
• ✅ Error Handling - Graceful failures with logging
• ✅ Comprehensive Tests - 13/13 test cases passing
• ✅ Zero Dependencies - No API key registration required
• ✅ Live Demo - See all prices with gainers/losers analysis
• ✅ Production Ready - Robust, tested, and documented

🎯 Quick Start

Prerequisites

• Python 3.8 or higher
• pip (Python package manager)

Installation

# Clone the repository
git clone https://github.com/ShreyashPatil530/crypto-mcp-server.git
cd crypto-mcp-server

# Install dependencies
pip install -r requirements.txt

# Create data directory
mkdir -p data

Run Live Demo

python live_demo.py

Output Example:

🔴 LIVE CRYPTOCURRENCY DATA - REAL-TIME PRICES
⏰ Time: 2025-12-09 21:02:04

[1/18] Fetching BTC... ✓ $91,064.23 📈 (+1.19%)
[2/18] Fetching ETH... ✓ $3,149.87 📈 (+1.38%)
[3/18] Fetching XRP... ✓ $2.08 📈 (+0.02%)
...
📋 SUMMARY TABLE - ALL CRYPTOCURRENCIES
Symbol     Price (USDT)       24h High           24h Low            Change %
BTC        $      91,064.23 $      91,374.00 $      89,500.00       1.19%
ETH        $       3,149.87 $       3,168.43 $       3,075.38       1.38%

🚀 TOP 5 GAINERS (24h)
1. ADA      $        0.46  📈 +6.30%
2. ARB      $        0.22  📈 +2.56%

Run Main Server

python main.py

Run Tests

python tests.py

Expected Output:

==================================================
🧪 Running Cryptocurrency MCP Server Tests
==================================================
Ran 13 tests in 19.702s
OK
✅ All tests passed! (13 tests)
==================================================

📁 Project Structure

crypto-mcp-server/
├── main.py                 # Entry point - MCP server main logic
├── api.py                  # CCXT API integration (fetch prices & history)
├── cache.py                # Caching system with TTL management
├── errors.py               # Error handling & validation
├── tests.py                # Comprehensive test suite (13 tests)
├── live_demo.py            # Live demo showing all cryptocurrencies
├── requirements.txt        # Python dependencies
├── README.md              # This file
├── .gitignore             # Git ignore rules
└── data/                  # Data storage directory
    ├── cache.json         # Cached cryptocurrency prices
    ├── live_prices.json   # Latest live prices (generated by live_demo)
    ├── errors.log         # Error logs
    └── .gitkeep           # Keep directory in git

🔧 API Reference

MCPServer Class

get_current_price(symbol)

Fetch real-time price and market data for a cryptocurrency.

from main import MCPServer

server = MCPServer()
btc = server.get_current_price('BTC')
print(f"Bitcoin: ${btc['price']:,.2f}")
print(f"24h Change: {btc['change_percent']}%")

Returns:

{
  "symbol": "BTC",
  "price": 91064.23,
  "high_24h": 91374.0,
  "low_24h": 89500.0,
  "volume": 1257916388.71,
  "bid": 91064.22,
  "ask": 91064.23,
  "change_percent": 1.19,
  "timestamp": "2025-12-09T21:02:04.123456"
}

get_multiple_prices(symbols)

Fetch prices for multiple cryptocurrencies at once.

prices = server.get_multiple_prices(['BTC', 'ETH', 'XRP'])
for symbol, data in prices.items():
    print(f"{symbol}: ${data['price']}")

get_historical_data(symbol, days=7)

Fetch historical OHLCV (Open, High, Low, Close, Volume) data.

history = server.get_historical_data('BTC', days=30)
for candle in history:
    print(f"{candle['date']}: Close ${candle['close']:,.2f}")

Returns:

[
  {
    "date": "2025-12-03T00:00:00",
    "open": 91277.88,
    "high": 94150.0,
    "low": 90990.23,
    "close": 93429.95,
    "volume": 156432189.45
  }
]

💾 Caching System

The server automatically caches cryptocurrency data to reduce API calls.

Cache File: data/cache.json

How it works:

1. First request → Fetches from Binance API → Saves to cache
2. Subsequent requests (within 5 min) → Uses cached data (instant response)
3. After 5 minutes → Cache expires → Fresh data fetched

Cache Configuration:

• TTL (Time To Live): 5 minutes
• Format: JSON
• Auto-cleanup: Expired entries removed automatically

Example Cache:

{
  "BTC": {
    "symbol": "BTC",
    "price": 91064.23,
    "timestamp": "2025-12-09T21:02:04.123456",
    "high_24h": 91374.0
  },
  "ETH": {
    "symbol": "ETH",
    "price": 3149.87,
    "timestamp": "2025-12-09T21:02:05.456789",
    "high_24h": 3168.43
  }
}

🧪 Test Coverage

13 comprehensive test cases covering all functionality:

CryptoAPI Tests (6 tests)

• ✓ Fetch BTC price (real-time)
• ✓ Fetch ETH price (real-time)
• ✓ Fetch multiple symbols
• ✓ Historical data retrieval (7 days)
• ✓ Invalid symbol error handling
• ✓ Supported symbols listing

CacheManager Tests (4 tests)

• ✓ Save and retrieve cache
• ✓ Cache expiration (TTL)
• ✓ Clear cache entries
• ✓ Cache file creation

ErrorHandler Tests (3 tests)

• ✓ Error handling and logging
• ✓ Symbol validation
• ✓ Days parameter validation

Run tests:

python tests.py

Performance:

Ran 13 tests in 19.702s
OK
✅ All tests passed!

🔗 Supported Cryptocurrencies

🛡️ Error Handling

All errors are logged and displayed gracefully.

Log File: data/errors.log

Example Error Output:

❌ ERROR [ValueError]
   Context: Invalid symbol
   Message: Symbol XYZ not supported
   Time: 2025-12-09T21:02:04.123456

Handled Errors:

• Invalid cryptocurrency symbols
• Network/API connection failures
• Invalid input parameters
• Cache read/write failures

⚙️ Configuration

Edit cache.py to customize cache behavior:

# Default: 5 minutes
cache = CacheManager(cache_file='data/cache.json', ttl_minutes=5)

# Custom: 10 minutes
cache = CacheManager(cache_file='data/cache.json', ttl_minutes=10)

# Custom: 1 minute (for frequent updates)
cache = CacheManager(cache_file='data/cache.json', ttl_minutes=1)

📊 Performance Benchmarks

🔑 Why No API Key?

This project uses CCXT's public API endpoints which don't require authentication:

• ✅ Real-time market data available
• ✅ Historical data available
• ✅ No rate limiting (reasonable usage)
• ✅ 100% Free
• ✅ No account registration needed
• ✅ Instant setup

Note: For high-frequency trading or increased rate limits, consider using authenticated API keys (not required for this project).

📦 Dependencies

ccxt==4.0.92          # Cryptocurrency exchange library
python-dateutil==2.8.2  # Date utilities
requests==2.31.0      # HTTP library

All dependencies are FREE and open-source.

🚀 Use Cases

1. Trading Bots - Fetch prices for automated trading strategies
2. Portfolio Trackers - Monitor multiple cryptocurrency holdings
3. Crypto Dashboards - Real-time market data visualization
4. Market Analysis - Historical data for technical analysis
5. AI/ML Models - Feed crypto data to machine learning models
6. Mobile Apps - Backend API for crypto price apps
7. Price Alerts - Monitor price changes and send notifications
8. Research - Academic cryptocurrency market research

🤝 Contributing

Contributions are welcome! Feel free to:

• Add more cryptocurrencies
• Implement new exchange APIs
• Improve caching mechanisms
• Enhance error handling
• Add more test cases
• Update documentation

Steps to contribute:

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

📋 Assumptions & Limitations

Assumptions:

1. Active internet connection required for API calls
2. Binance API is accessible (not blocked in your region)
3. All prices denominated in USDT (US Dollar Tether)
4. Default cache expiration: 5 minutes
5. Reasonable API usage (not high-frequency trading)

Limitations:

1. Real-time data update interval: ~1-2 seconds (API rate limit)
2. Historical data limited to last 365 days
3. No support for spot margin trading or derivatives
4. Single exchange (Binance) - easily extensible to multiple exchanges

🐛 Troubleshooting

Issue: "No module named 'ccxt'"

Solution:

pip install -r requirements.txt

Issue: "Connection timeout"

Solution:

• Check your internet connection
• Ensure Binance API is accessible in your region
• Try using a VPN if blocked

Issue: "Symbol not supported"

Solution: Use one of the 18 supported symbols (BTC, ETH, XRP, etc.)

Issue: "Permission denied" (Windows)

Solution:

python -m pip install --upgrade pip
pip install -r requirements.txt

Issue: "ModuleNotFoundError"

Solution:

# Reinstall all dependencies
pip install --upgrade -r requirements.txt

📞 Support & Questions

For issues, questions, or suggestions:

1. Check test cases in tests.py for usage examples
2. Review README examples above
3. Check error logs in data/errors.log
4. Open an issue on GitHub

📄 License

This project is licensed under the MIT License - see the file for details.

You are free to use, modify, and distribute this software.

🙏 Acknowledgments

• CCXT - Cryptocurrency exchange library
• Binance - Free public API
• Python Community - For amazing tools and libraries

📈 Project Statistics

• Lines of Code: ~800
• Test Coverage: 13/13 tests passing (100%)
• Supported Cryptocurrencies: 18+
• API Integrations: CCXT (Binance)
• Cache System: Yes (5 min TTL)
• Error Handling: Comprehensive
• Documentation: Complete
• License: MIT (Open Source)

🎯 Roadmap

Future enhancements (potential features):

• Multiple exchange support (Coinbase, Kraken, etc.)
• WebSocket real-time price streaming
• Database integration (PostgreSQL, MongoDB)
• REST API wrapper
• Docker containerization
• Price alert system
• Portfolio management features
• Advanced charting capabilities

👨‍💻 Author

Shreyash Patil

• GitHub: @ShreyashPatil530
• Project: crypto-mcp-server

📅 Project Timeline

• Created: December 2025
• Last Updated: December 9, 2025
• Status: ✅ Complete & Production Ready
• Version: 1.0.0

Made with ❤️ for the crypto community | MIT License | Open Source

🌟 Give a Star!

If this project helped you, please consider giving it a ⭐ on GitHub!

https://github.com/ShreyashPatil530/crypto-mcp-server

Thank you for using Cryptocurrency MCP Server! 🚀