🚀 Luno MCP Server - FastMCP 2.0

A modern Model Context Protocol (MCP) server for the Luno cryptocurrency exchange, built with FastMCP 2.0 and Python 3.12.

✅ Quick Start

1. Install Dependencies

# Activate the virtual environment
source venv/bin/activate

# Dependencies are already installed:
# - fastmcp 2.5.1
# - httpx
# - pydantic
# - python-dotenv

2. Configure Claude Desktop

Add this to your ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "luno": {
      "command": "/Users/aman-asmuei/Documents/mcp/mcp-luno/venv/bin/python",
      "args": [
        "/Users/aman-asmuei/Documents/mcp/mcp-luno/src/luno_mcp_server/server.py"
      ],
      "cwd": "/Users/aman-asmuei/Documents/mcp/mcp-luno",
      "env": {
        "LUNO_API_KEY": "your_api_key_here",
        "LUNO_API_SECRET": "your_api_secret_here"
      }
    }
  }
}

3. Test

Restart Claude Desktop and ask:

• "What's the Bitcoin price in EUR?"
• "Get ETHZAR price"
• "Show me my account balance"
• "Get historical prices for XBTZAR over the last 7 days"
• "Show me Bitcoin price range analysis for the past 30 days"

🛠️ Available Tools

Public Tools (No API credentials required)

• get_crypto_price - Real-time prices for any trading pair
• get_market_overview - Market data and available pairs

Historical Data Tools (API credentials required)

• get_historical_prices - OHLC candlestick data for any trading pair
• get_price_range - Price analysis over specified time periods (1-30 days)

Private Tools (API credentials required)

• get_account_balance - Account balances
• place_order - Place buy/sell orders
• cancel_order - Cancel orders
• get_order_status - Check order status
• get_transaction_history - Transaction history
• get_fees - Trading fees

📈 Historical Price Data Features

Candlestick Data (get_historical_prices)

• Timeframes: 1m, 5m, 15m, 30m, 1h, 3h, 4h, 8h, 24h, 3d, 7d
• Data: OHLC (Open, High, Low, Close) + Volume
• Limit: Up to 1000 candles per request
• Format: Standard candlestick data with timestamps

Price Range Analysis (get_price_range)

• Period: 1-30 days of historical data
• Statistics: High, Low, Open, Close, Average prices
• Metrics: Price change, percentage change, total volume
• Convenience: Automatic daily candle aggregation

🌍 Supported Trading Pairs

• ZAR (South Africa): XBTZAR, ETHZAR, ADAZAR
• EUR (Europe): XBTEUR, ETHEUR
• GBP (UK): XBTGBP, ETHGBP, SOLGBP
• USD (US): XBTUSD, ETHUSD
• And more!

🏗️ Project Structure

luno-mcp/
├── src/
│   ├── luno_mcp/              # Modern FastMCP 2.0 implementation
│   │   ├── server.py          # Main server with all tools
│   │   ├── client.py          # Luno API client
│   │   ├── config.py          # Configuration management
│   │   └── tools/             # Modular tool organization
│   ├── luno_mcp_server/       # Working FastMCP server (CURRENT)
│   │   ├── server.py          # ← Currently used by Claude Desktop
│   │   └── luno_client.py     # Luno API client
│   └── main.py                # Alternative entry point
├── tests/                     # Test suite
├── docs/                      # Documentation
├── archive/                   # Old implementations
├── venv/                      # Python 3.12 virtual environment
└── README.md                  # This file

🔧 Technical Details

• Python: 3.12.10 (in virtual environment)
• Framework: FastMCP 2.5.1
• API Client: httpx for async HTTP requests
• Transport: STDIO (JSON-RPC 2.0)
• Architecture: Async/await with proper error handling

📚 Documentation

• docs/PYTHON_UPGRADE_GUIDE.md - Python upgrade process
• docs/MIGRATION.md - Migration from old versions
• docs/CLAUDE_DESKTOP_SETUP.md - Detailed setup guide
• docs/GITHUB_PAGES_FIX.md - Fix GitHub Pages deployment errors

📚 Documentation Site

Visit our GitHub Pages documentation: https://amanasmuei.github.io/mcp-luno

Note: If you encounter GitHub Pages deployment errors, see docs/GITHUB_PAGES_FIX.md for the complete fix guide.

🔒 Security

• API credentials stored as environment variables
• All communications use HTTPS
• Virtual environment isolation
• No credentials logged or exposed

🚨 Troubleshooting

Common Issues

1. Import errors: Make sure you're using the virtual environment
2. API errors: Check your Luno API credentials
3. Connection issues: Verify internet connectivity

Get Help

1. Check the logs in Claude Desktop
2. Test the server directly: python src/luno_mcp_server/server.py
3. Verify dependencies: pip list | grep fastmcp

💖 Support This Project

If this Luno MCP server has been helpful for your cryptocurrency trading and analysis, consider supporting its development!

☕ Support This Project

🌍 Global donation options that work worldwide:

• 💖 GitHub Sponsors: github.com/sponsors/amanasmuei (Monthly/one-time)
• 💳 PayPal.me: paypal.me/amanasmuei (Direct payments)
• ⭐ Star this repo on GitHub
• 🐛 Report issues and contribute improvements
• 📢 Share with other crypto traders

🪙 Crypto Donations

• Bitcoin (BTC): 3CPb1HP6Gfpx3MZFdrm4nhoHk4VbX2eZRj
• Ethereum (ETH): 0x54dC4eDf6c940C52A1434824634d8cE8629767b3
• Luno Trading: Use this MCP server to trade! 📈

Your support helps maintain and improve this free, open-source trading tool! 🚀

---

🎉 Success!

You should now have a fully working Luno MCP server with:

• ✅ Real-time cryptocurrency prices
• ✅ Historical price data and candlestick charts
• ✅ Price range analysis and statistics
• ✅ Multi-currency support (ZAR, EUR, GBP, USD)
• ✅ Account management tools
• ✅ Trading capabilities
• ✅ FastMCP 2.0 architecture

Ask Claude: "What's the Bitcoin price in EUR?" or "Show me XBTZAR price history for the past week" to test!