mcp_crypto_server

Spoorthy1423/mcp_crypto_server

3.2

If you are the rightful owner of mcp_crypto_server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The CryptoMarket Platform is an enterprise-grade cryptocurrency market data platform with a comprehensive Python-based Model Context Protocol (MCP) server, providing real-time and historical data from major exchanges.

Tools
3
Resources
0
Prompts
0

CryptoMarket Platform

Enterprise-grade cryptocurrency market data platform with production-ready DevOps infrastructure.

A comprehensive Python-based Model Context Protocol (MCP) server that provides real-time and historical cryptocurrency market data from major exchanges using CCXT. Built with modern DevOps practices including Docker containerization, CI/CD pipelines, comprehensive testing, and cross-platform support.

Features

Core Functionality

  • ✅ Real-time Price Data: Get current ticker prices for any cryptocurrency pair
  • ✅ Historical OHLC Data: Fetch Open, High, Low, Close candlestick data
  • ✅ Live Price Streaming: Stream real-time price updates every 2 seconds
  • ✅ Intelligent Caching: In-memory cache to reduce API calls and respect rate limits
  • ✅ Error Handling: Robust error handling throughout the application
  • ✅ Comprehensive Tests: Full test coverage for all tools and services

DevOps & Production Features

  • 🐳 Docker Containerization: Production-ready Dockerfile with multi-stage optimization
  • 🔄 CI/CD Pipeline: Automated testing, linting, and deployment with GitHub Actions
  • 🧪 Automated Testing: Comprehensive pytest test suite with async support
  • 📦 Cross-Platform Support: Works on macOS, Linux, and Windows
  • 🔒 Security Best Practices: Non-root user in containers, proper dependency management
  • 📊 Code Quality: Linting, formatting checks, and syntax validation
  • 🚀 Deployment Ready: Supports deployment to cloud platforms (AWS, Azure, GCP, etc.)

Requirements

  • Python 3.10 or higher (MCP SDK requires Python 3.10+)
  • pip package manager
  • Platform Support: Works on macOS, Linux, and Windows

Note: The application is cross-platform. The CI/CD pipeline runs on Ubuntu (GitHub Actions), but the Python code itself works on all platforms. Docker containers are Linux-based, but Docker Desktop on Mac/Windows runs them seamlessly.

Installation

Platform-Specific Notes

  • macOS: Works natively. Use python3 or python depending on your setup.
  • Linux: Works natively. May need python3 instead of python.
  • Windows: Works natively. Use python or py command.

1. Clone the repository

git clone <your-repo-url>
cd mcp-crypto-server

2. Install dependencies

On macOS/Linux:

# Install MCP SDK from GitHub (requires Python 3.10+)
pip3 install git+https://github.com/modelcontextprotocol/python-sdk.git

# Install other dependencies
pip3 install -r requirements.txt

On Windows:

# Install MCP SDK from GitHub (requires Python 3.10+)
pip install git+https://github.com/modelcontextprotocol/python-sdk.git

# Install other dependencies
pip install -r requirements.txt

Or install all at once (all platforms):

# Install MCP SDK from GitHub (requires Python 3.10+)
pip install git+https://github.com/modelcontextprotocol/python-sdk.git

# Install other dependencies
pip install -r requirements.txt

Or install all at once:

pip install git+https://github.com/modelcontextprotocol/python-sdk.git ccxt>=4.0.0 pytest>=7.0.0 pytest-asyncio>=0.21.0

3. Verify installation

python -m py_compile app/main.py
echo "✓ Installation successful"

Usage

Running the Server

python -m app.main

Or:

python app/main.py

The server will start and be ready to accept MCP client connections via server.json.

Available Tools

  1. ticker(symbol: str)

    • Fetches the latest ticker price for a cryptocurrency pair
    • Example: ticker("BTC/USDT")
    • Returns: {"symbol": "BTC/USDT", "price": 50000, "timestamp": 1234567890}
    • Uses caching (2-second TTL) to reduce API calls

  2. ohlc_history(symbol: str, timeframe: str = "1m", limit: int = 100)

    • Fetches historical OHLC (Open, High, Low, Close) candlestick data
    • Example: ohlc_history("BTC/USDT", "1h", 50)
    • Returns: Array of candlestick objects with timestamp, open, high, low, close, volume

  3. stream_price(symbol: str, context)

    • Streams live price updates every 2 seconds
    • Example: stream_price("BTC/USDT", context)
    • Sends events: price_update with latest price data

Configuration

Edit app/core/config.py to customize:

  • DEFAULT_EXCHANGE: Exchange to use (default: "binance")
  • DEFAULT_TIMEFRAME: Default timeframe for OHLC (default: "1m")
  • DEFAULT_LIMIT: Default number of candles (default: 100)

Testing

Run the test suite:

pytest tests/ -v

Run specific test files:

pytest tests/test_prices.py -v
pytest tests/test_history.py -v

Docker

Note: Docker containers run Linux, but Docker Desktop on Mac and Windows handles this automatically. The containerized app works the same on all platforms.

Prerequisites

Build the Docker image

docker build -t mcp-crypto-server .

Run with Docker

docker run --rm mcp-crypto-server

Using Docker Compose

docker-compose up

macOS/Windows Note: Docker Desktop must be running before executing Docker commands.

CI/CD Pipeline

The project includes GitHub Actions workflows:

  1. .github/workflows/ci-cd.yml: Main CI/CD pipeline

    • Runs on push/PR to main/master branches
    • Tests code compilation
    • Runs pytest tests
    • Builds Docker image
    • Optional deployment steps

  2. .github/workflows/docker-publish.yml: Docker image publishing

    • Builds and pushes Docker images to Docker Hub
    • Tags images with version, branch, and SHA
    • Requires DOCKER_USERNAME and DOCKER_PASSWORD secrets

Setting up GitHub Secrets

For Docker Hub publishing, add these secrets in your GitHub repository:

  1. Go to Settings → Secrets and variables → Actions
  2. Add:
    • DOCKER_USERNAME: Your Docker Hub username
    • DOCKER_PASSWORD: Your Docker Hub password/token

Project Structure

cryptomarket-platform/
├── app/
│   ├── core/
│   │   └── config.py          # Configuration settings
│   ├── services/
│   │   ├── ccxt_client.py      # CCXT exchange client
│   │   └── cache.py            # In-memory caching
│   ├── tools/
│   │   ├── prices.py           # Price tools (ticker, stream_price)
│   │   └── history.py          # Historical data tools (ohlc_history)
│   └── main.py                 # MCP server entry point
├── tests/
│   ├── test_prices.py          # Tests for price tools
│   └── test_history.py         # Tests for history tools
├── .github/
│   └── workflows/
│       ├── ci-cd.yml           # Main CI/CD pipeline
│       └── docker-publish.yml  # Docker publishing workflow
├── Dockerfile                  # Docker container definition
├── docker-compose.yml          # Docker Compose configuration
├── .dockerignore              # Docker ignore patterns
├── requirements.txt           # Python dependencies
├── server.json                # MCP server configuration
└── README.md                  # This file

Architecture

  • MCP Server: Uses the Model Context Protocol Python SDK
  • CCXT Integration: Unified API for multiple cryptocurrency exchanges
  • Caching Layer: Reduces API calls and respects rate limits
  • Async/Await: Fully asynchronous for better performance
  • Error Handling: Comprehensive error handling with user-friendly messages

Supported Exchanges

The server uses CCXT, which supports 100+ exchanges including:

  • Binance (default)
  • Coinbase
  • Kraken
  • Bitfinex
  • And many more...

Change the exchange in app/core/config.py or pass it as a parameter.

Development

Adding New Tools

  1. Create a new function in app/tools/
  2. Decorate with @tool() or @stream()
  3. Import in app/main.py
  4. Add tests in tests/

Code Style

  • Follow PEP 8 Python style guide
  • Use type hints where possible
  • Add docstrings to all functions
  • Write tests for new features

Troubleshooting

Platform-Specific Issues

macOS:

  • If python doesn't work, use python3
  • If pip doesn't work, use pip3
  • Install Python 3.10+ via Homebrew: brew install python@3.11

Windows:

  • Use py command if python doesn't work: py -m pip install ...
  • Ensure Python 3.10+ is added to PATH

Linux:

  • Use python3 and pip3 commands
  • Install Python 3.10+ via your package manager

MCP Package Installation Issues

If you get errors installing MCP:

  • Ensure Python 3.10+ is installed: python --version or python3 --version
  • Install directly from GitHub: pip install git+https://github.com/modelcontextprotocol/python-sdk.git
  • On macOS/Linux, you may need: pip3 install git+https://github.com/modelcontextprotocol/python-sdk.git

Exchange API Errors

  • Check internet connection
  • Verify the symbol format (e.g., "BTC/USDT")
  • Some exchanges may require API keys (not currently implemented)

Docker Build Issues

  • Ensure Docker is running: docker ps
  • Check Dockerfile uses Python 3.11 (MCP requires 3.10+)
  • Review build logs for specific errors

License

[Add your license here]

Contributing

[Add contribution guidelines here]

Acknowledgments