🪙 Crypto MCP Server

A FastMCP server providing real-time cryptocurrency data from the API Ninjas Crypto API.

This server exposes tools via the Model Context Protocol (MCP) allowing compatible clients (like Claude, Cursor, etc.) to easily query cryptocurrency symbols and their current prices.

✨ Features

• List Symbols: Get a list of all available cryptocurrency symbols.
• Get Price: Fetch the current price and timestamp for a specific symbol.
• MCP Compliant: Built using FastMCP for standard MCP communication.
• Async API Client: Uses httpx for efficient, non-blocking API calls.
• Validated Data: Uses pydantic for robust data validation.
• Tested: Includes unit and integration tests (pytest).

🚀 Getting Started

Follow these steps to set up and run the server locally.

Prerequisites

• Python 3.10 or higher
• git
• A virtual environment tool (like venv or uv)
• An API Key from API Ninjas (specifically for the Crypto API)

Installation & Setup

1. Clone the repository:

   git clone https://github.com/<your-username>/crypto-mcp-server.git # Replace with actual repo URL
   cd crypto-mcp-server
   

2. Create and activate a virtual environment: Using venv (standard library):

   python3 -m venv venv
   source venv/bin/activate # On Windows use `venv\Scripts\activate`
   

   Using uv (if installed):

   uv venv venv
   source venv/bin/activate
   

3. Install dependencies: Using pip (with venv):

   pip install -e ".[dev]" # Installs in editable mode + dev dependencies
   

   *Using uv:

   uv sync --all-features
   

4. Create .env file: Create a file named .env in the project root directory and add your API key:

   API_NIINJAS_API_KEY="YOUR_API_NINJAS_CRYPTO_API_KEY"
   

   Replace YOUR_API_NINJAS_CRYPTO_API_KEY with the actual key you obtained.

Running the Server

Once set up, you can run the MCP server using the fastmcp command:

fastmcp run main.py

The server will typically start on http://127.0.0.1:8000.

You can then connect your MCP client to this address.

🛠️ Available Tools

The server exposes the following tools to MCP clients:

• list_crypto_symbols():
  • Description: Fetches a list of all available cryptocurrency symbols from the API.
  • Returns: List[str] - A list of symbol strings (e.g., ['BTCUSD', 'ETHBTC', ...]).
• get_crypto_price(symbol: str):
  • Description: Fetches the current price and timestamp for a specific cryptocurrency symbol.
  • Args:
    • symbol (str): The cryptocurrency symbol (e.g., 'BTCUSD', 'ETHBTC'). Use list_crypto_symbols to find available symbols.
  • Returns: Dict[str, Any] - A dictionary containing the symbol, its price (as a string), and the Unix timestamp (e.g., {'symbol': 'BTCUSD', 'price': '65432.10', 'timestamp': 1678886400}).
  • Raises: ValueError if the symbol is not found or invalid.

🧪 Development & Testing

To run the tests:

1. Ensure you have installed the development dependencies (pip install -e ".[dev]" or uv sync --all-features).
2. Run pytest:

   pytest -v
   

Integration tests require a valid API_NIINJAS_API_KEY in your .env file and will be skipped otherwise.

🙏 Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details (assuming MIT, create LICENSE file if needed).