https://github.com/amanasmuei/mcp-luno
mcp server for luno
https://github.com/amanasmuei/mcp-luno
Last synced: 2 months ago
JSON representation
mcp server for luno
- Host: GitHub
- URL: https://github.com/amanasmuei/mcp-luno
- Owner: amanasmuei
- Created: 2025-05-16T03:10:33.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-05-28T09:12:18.000Z (6 months ago)
- Last Synced: 2025-05-28T10:25:27.062Z (6 months ago)
- Language: Python
- Size: 49.8 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
- awesome-mcp-servers - **mcp-luno** - mcp server for luno (Python-based) `python` `mcp` `server` `pip install git+https://github.com/amanasmuei/mcp-luno` (🤖 AI/ML)
README
# 🚀 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
```bash
# 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`:
```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`](docs/PYTHON_UPGRADE_GUIDE.md) - Python upgrade process
- [`docs/MIGRATION.md`](docs/MIGRATION.md) - Migration from old versions
- [`docs/CLAUDE_DESKTOP_SETUP.md`](docs/CLAUDE_DESKTOP_SETUP.md) - Detailed setup guide
- [`docs/GITHUB_PAGES_FIX.md`](docs/GITHUB_PAGES_FIX.md) - Fix GitHub Pages deployment errors
## 📚 Documentation Site
Visit our GitHub Pages documentation: [https://amanasmuei.github.io/mcp-luno](https://amanasmuei.github.io/mcp-luno)
> **Note**: If you encounter GitHub Pages deployment errors, see [`docs/GITHUB_PAGES_FIX.md`](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
[](https://github.com/sponsors/amanasmuei)
**🌍 Global donation options that work worldwide:**
- 💖 **GitHub Sponsors:** [github.com/sponsors/amanasmuei](https://github.com/sponsors/amanasmuei) *(Monthly/one-time)*
- 💳 **PayPal.me:** [paypal.me/amanasmuei](https://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!**