PiyushGupta-45/Python-based-MCP-server

Cryptocurrency MCP Server

A Python-based Model Context Protocol (MCP) server for retrieving real-time and historical cryptocurrency market data from major exchanges using CCXT.

Features

• Real-time Market Data: Get current prices, bids, asks, and volumes for any trading pair
• Historical Data: Retrieve OHLCV (candlestick) data with customizable timeframes
• Order Book Data: Access bid/ask order book information
• Trade History: Fetch recent trades for any trading pair
• Multi-Exchange Support: Works with Binance, Coinbase, Kraken, Bitfinex, Huobi, OKX, and Bybit
• Intelligent Caching: Built-in caching layer to reduce API calls and improve performance
• Rate Limiting: Automatic rate limiting to respect exchange API limits
• Error Handling: Robust error handling and logging
• Comprehensive Tests: Full test coverage

Supported Exchanges

• Binance
• Coinbase
• Kraken
• Bitfinex
• Huobi
• OKX
• Bybit

Installation

1. Clone the repository:

git clone <repository-url>
cd inter

2. Install dependencies:

pip install -r requirements.txt

Or install in development mode:

pip install -e ".[dev]"

3. (Optional) Configure API keys by creating a .env file:

BINANCE_API_KEY=your_api_key
BINANCE_SECRET=your_secret
COINBASE_API_KEY=your_api_key
COINBASE_SECRET=your_secret

Note: Most public endpoints don't require API keys, but some exchanges may have rate limits for unauthenticated requests.

Usage

Quick Start

Option 1: Web Dashboard (Recommended for Testing)

python web_dashboard.py

Then open http://localhost:5000 in your browser to see and test the server.

Option 2: MCP Server (For MCP Client Integration)

python run_server.py

The server will wait for MCP client connections via stdio.

Option 3: Test Components

python test_server_standalone.py

Test the crypto provider directly without the full server.

Running the MCP Server

Important: The MCP server is designed to run via stdio and requires an MCP client connection. It will wait for MCP protocol messages on stdin and respond on stdout.

Start the server:

python -m src.server

Or use the entry point:

python run_server.py

The server communicates via stdio (standard input/output) following the MCP protocol. When running standalone, it will wait for MCP client connections.

Note: If the server appears to stop after a few minutes when running standalone, this is normal behavior. The server is waiting for MCP protocol messages. To test the components directly, use:

python test_server_standalone.py

Web Dashboard

For a visual interface to test and monitor the server, use the web dashboard:

python web_dashboard.py

Then open http://localhost:5000 in your browser. The dashboard provides:

• Server status monitoring
• Interactive tool testing
• Real-time data visualization
• Server information display

Available Tools

The server provides the following tools:

1. get_ticker

Get real-time ticker data for a trading pair.

Parameters:

• symbol (required): Trading pair symbol (e.g., "BTC/USDT", "ETH/USD")
• exchange (optional): Exchange name (defaults to "binance")

Example:

{
  "symbol": "BTC/USDT",
  "exchange": "binance"
}

2. get_ohlcv

Get historical OHLCV (candlestick) data.

Parameters:

• symbol (required): Trading pair symbol
• timeframe (optional): Timeframe (1m, 5m, 15m, 1h, 4h, 1d, 1w, 1M) - default: "1h"
• limit (optional): Number of candles (default: 100, max: 1000)
• since (optional): Start timestamp in milliseconds
• exchange (optional): Exchange name

Example:

{
  "symbol": "BTC/USDT",
  "timeframe": "1h",
  "limit": 100
}

3. get_orderbook

Get order book (bids and asks) for a trading pair.

Parameters:

• symbol (required): Trading pair symbol
• limit (optional): Number of orders (default: 20, max: 100)
• exchange (optional): Exchange name

Example:

{
  "symbol": "BTC/USDT",
  "limit": 20
}

4. get_trades

Get recent trades for a trading pair.

Parameters:

• symbol (required): Trading pair symbol
• limit (optional): Number of trades (default: 50, max: 500)
• since (optional): Start timestamp in milliseconds
• exchange (optional): Exchange name

Example:

{
  "symbol": "BTC/USDT",
  "limit": 50
}

5. get_markets

Get all available trading pairs for an exchange.

Parameters:

• exchange (optional): Exchange name

Example:

{
  "exchange": "binance"
}

6. get_supported_exchanges

Get list of supported exchanges.

Parameters: None

Configuration

Configuration can be set via environment variables or a .env file:

• CACHE_TTL_SECONDS: Cache time-to-live in seconds (default: 60)
• MAX_CACHE_SIZE: Maximum cache entries (default: 1000)
• RATE_LIMIT_REQUESTS_PER_SECOND: Rate limit (default: 10)
• DEFAULT_EXCHANGE: Default exchange name (default: "binance")
• BINANCE_API_KEY: Binance API key (optional)
• BINANCE_SECRET: Binance API secret (optional)
• COINBASE_API_KEY: Coinbase API key (optional)
• COINBASE_SECRET: Coinbase API secret (optional)

Testing

Run the test suite:

pytest

Run with coverage:

pytest --cov=src --cov-report=html

Run specific test file:

pytest tests/test_cache.py

Project Structure

inter/
├── src/
│   ├── __init__.py          # Package initialization
│   ├── server.py            # MCP server implementation
│   ├── crypto_provider.py   # CCXT-based data provider
│   ├── cache.py             # Caching layer
│   ├── config.py            # Configuration management
│   └── errors.py            # Custom error classes
├── tests/
│   ├── __init__.py
│   ├── conftest.py          # Pytest configuration
│   ├── test_cache.py        # Cache tests
│   ├── test_crypto_provider.py  # Provider tests
│   ├── test_server.py       # Server tests
│   └── test_config.py      # Config tests
├── requirements.txt         # Python dependencies
├── pyproject.toml          # Project configuration
└── README.md              # This file

Architecture

Components

1. MCP Server (src/server.py): Implements the MCP protocol, handles tool registration and execution
2. Crypto Provider (src/crypto_provider.py): Wraps CCXT library to fetch data from exchanges
3. Cache Layer (src/cache.py): Implements TTL-based caching to reduce API calls
4. Configuration (src/config.py): Manages application settings and environment variables

Design Patterns

• Async/Await: All I/O operations are asynchronous for better performance
• Caching: TTL-based cache reduces redundant API calls
• Rate Limiting: Semaphore-based rate limiting prevents API abuse
• Error Handling: Comprehensive error handling with custom exception classes

Best Practices

• The server uses async/await for all network operations
• Caching is implemented to minimize API calls and improve response times
• Rate limiting prevents exceeding exchange API limits
• All components are thoroughly tested
• Code follows Python best practices and PEP 8 style guidelines

Limitations

• Some exchanges may have rate limits for unauthenticated requests
• Historical data availability depends on the exchange
• Not all exchanges support all timeframes
• Cache TTL should be adjusted based on use case (real-time vs. historical data)

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

This project is open source and available under the MIT License.

Acknowledgments

• Built with CCXT for exchange connectivity
• Uses MCP protocol for AI integration