Luno MCP 服务器

Luno 加密货币交易所 API 的模型上下文协议 (MCP) 服务器。该服务器为 AI 模型和应用程序提供标准化接口，以便与 Luno API 进行加密货币交易交互。

 _                        __  __  ____ ____   
| |    _   _ _ __   ___  |  \/  |/ ___|  _ \  
| |   | | | | '_ \ / _ \ | |\/| | |   | |_) | 
| |___| |_| | | | | (_) || |  | | |___|  __/  
|_____|\__,_|_| |_|\___/ |_|  |_|\____|_|     

特征

通过 Luno API 获取实时加密货币价格信息
所有交易对的市场概览
账户余额查询
订单管理（下单、取消、状态）
交易历史记录检索
费用信息
标准化 JSON-RPC 2.0 接口
与 AI 应用程序简单集成

先决条件

Python 3.8+（建议使用 Python 3.9+）
uv用于包管理
带有 API 密钥的 Luno 帐户（用于完整功能）

安装

克隆此存储库

git clone https://github.com/amanasmuei/mcp-luno.git
cd mcp-luno

使用uv创建虚拟环境

uv venv
source .venv/bin/activate  # On macOS/Linux
# On Windows use: .venv\Scripts\activate

安装依赖项

uv pip install -r requirements.txt

配置您的 Luno API 凭证（选择一种方法）：

Docker 支持

您可以使用 Docker 运行 MCP 服务器，以便在不同平台上更轻松地部署和保持一致的环境。

使用 Docker Compose（推荐）

复制示例环境文件并配置您的凭据：

cp .env.example .env
# Edit .env file with your Luno API credentials

启动服务器：

docker compose up -d

该服务器将在 WebSocket 模式下在ws://localhost:8765处可用。

查看日志：

docker compose logs -f

停止服务器：

docker compose down

直接使用 Docker

构建图像：

docker build -t mcp-luno .

运行容器：

docker run -d \
  -p 8765:8765 \
  -e LUNO_API_KEY=your_api_key_here \
  -e LUNO_API_SECRET=your_api_secret_here \
  -e MCP_TRANSPORT=websocket \
  -e MCP_HOST=0.0.0.0 \
  -v ./certs:/app/certs \
  --name mcp-luno \
  mcp-luno

与人工智能助手一起使用

启动Docker容器后，可以连接各种AI助手使用Luno MCP服务器：

光标

将以下内容添加到您的 Cursor 配置中：

{
  "mcp_servers": {
    "luno": {
      "type": "websocket",
      "url": "ws://localhost:8765"
    }
  }
}

克劳德桌面

在 Claude Desktop 设置中，您有两个选项可以配置 MCP 服务器：

选项 1：使用 Docker（推荐）

{
  "mcpServers": {
    "luno": {
      "command": "docker",
      "args": ["compose", "up"],
      "cwd": "/path/to/mcp-luno",
      "transport": "websocket",
      "url": "ws://localhost:8765",
      "env": {
        "LUNO_API_KEY": "your_api_key_here",
        "LUNO_API_SECRET": "your_api_secret_here"
      }
    }
  }
}

此配置在 Docker 容器中启动服务器并通过 WebSocket 连接。

选项 2：使用直接 Python 执行

{
  "mcpServers": {
    "luno": {
      "command": "python",
      "args": ["-m", "src.main", "--transport", "stdio"],
      "cwd": "/path/to/mcp-luno",
      "transport": "stdio",
      "env": {
        "PYTHONPATH": "${workspaceFolder}",
        "LUNO_API_KEY": "your_api_key_here",
        "LUNO_API_SECRET": "your_api_secret_here"
      }
    }
  }
}

此配置使用 STDIO 传输直接运行 Python 服务器。

注意：将/path/to/mcp-luno替换为您克隆存储库的实际路径。

克莱恩

将以下内容添加到您的 Cline 配置文件中：

{
  "mcp": {
    "servers": {
      "luno": {
        "transport": "websocket",
        "url": "ws://localhost:8765"
      }
    }
  }
}

Docker 的 SSL 支持

要在 Docker 容器中使用 SSL：

使用提供的脚本生成证书：

./generate_certificates.sh

docker run -d \
  -p 8765:8765 \
  -e LUNO_API_KEY=your_api_key_here \
  -e LUNO_API_SECRET=your_api_secret_here \
  -e MCP_TRANSPORT=websocket \
  -e MCP_HOST=0.0.0.0 \
  -v ./certs:/app/certs \
  --name mcp-luno \
  mcp-luno

手动安装

选项 A ：使用.env文件

cp .env.example .env

然后编辑.env文件以添加您的 Luno API 凭据：

LUNO_API_KEY=your_api_key_here
LUNO_API_SECRET=your_api_secret_here

选项 B ：使用 VS Code MCP 配置

编辑.vscode/mcp.json文件并将您的凭据添加到env部分：

"env": {
  "PYTHONPATH": "${workspaceFolder}",
  "LUNO_API_KEY": "your_api_key_here",
  "LUNO_API_SECRET": "your_api_secret_here",
  "LOG_LEVEL": "INFO"
}

注意：如果没有有效的 API 凭证，则只能使用公共端点。建议：为了安全起见，共享代码时最好使用环境变量。

运行服务器

您可以在两种不同的传输模式下运行 MCP 服务器：

STDIO 传输（默认，单客户端）

这是默认模式，它支持通过标准输入/输出的单个客户端连接：

python -m src.main --transport stdio

WebSockets 传输（多个客户端）

为了同时支持多个客户端连接，请以 WebSocket 模式运行服务器：

python -m src.main --transport websocket [--host HOST] [--port PORT]

WebSocket 服务器默认从ws://localhost:8765启动。

测试 WebSocket 服务器

您可以使用附带的测试客户端测试 WebSocket 服务器：

python test_websocket_client.py

这有助于验证服务器是否正确处理 WebSocket 连接并响应请求。

命令行选项

--transport {stdio,websocket} ：要使用的传输机制（默认值：stdio）
--host HOST ：使用 WebSocket 传输时绑定的主机（默认值：localhost）
--port PORT ：使用 WebSocket 传输时绑定的端口（默认值：8765）

环境变量

您还可以使用环境变量配置传输：

MCP_TRANSPORT ：传输机制（“stdio”或“websocket”）
MCP_HOST ：绑定到 WebSocket 传输的主机
MCP_PORT ：绑定到 WebSocket 传输的端口

使用标准客户端进行测试

要测试 STDIO 传输，请使用附带的测试客户端：

python test_client.py

MCP 协议集成

该服务器实现了模型上下文协议 (MCP)，允许 AI 模型通过标准化的 JSON-RPC 2.0 消息与其交互。该服务器默认通过 STDIO 运行，因此易于与 VS Code 扩展程序和其他兼容 MCP 的客户端集成。

VS Code 集成

.vscode/mcp.json文件用于配置 VS Code 使用的服务器。提供了两种服务器配置：

luno-mcp-server-stdio - 使用 STDIO 传输（默认 MCP 行为）
luno-mcp-server-websocket - 使用 WebSocket 传输实现多客户端支持

VS Code 配置

要将 WebSocket 传输与 VS Code 一起使用， mcp.json文件包含一个进程类型配置：

"luno-mcp-server-websocket": {
  "type": "process",
  "command": "python",
  "args": ["-m", "src.main", "--transport", "websocket"],
  "env": {
    // environment variables
  }
}

当使用 WebSocket 传输时，VS Code 将作为后台进程启动服务器，而不是通过 STDIO 进行通信。

在 VS Code 中配置 MCP 服务器

您可以直接从.vscode/mcp.json文件配置服务器：

{
  "servers": {
    "luno-mcp-server": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "src.main"],
      "env": {
        "PYTHONPATH": "${workspaceFolder}",
        "LUNO_API_KEY": "your_api_key_here",
        "LUNO_API_SECRET": "your_api_secret_here",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

此配置将被支持 MCP 协议的 VS Code 扩展使用，从而轻松与 AI 模型和其他工具集成。

可用方法

方法	描述	需要身份验证
`describe_capabilities`	返回有关服务器功能的信息	不
`get_crypto_price`	获取特定交易对的当前价格	不
`get_market_overview`	了解所有可用市场的概况	不
`get_account_balance`	获取所有账户的余额	是的
`place_order`	下新订单	是的
`cancel_order`	取消现有订单	是的
`get_order_status`	获取订单状态	是的
`get_transaction_history`	获取账户的交易历史记录	是的
`get_fees`	获取交易对的费用信息	是的

示例请求

获取服务器功能：

{
  "jsonrpc": "2.0",
  "method": "describe_capabilities",
  "params": {},
  "id": 1
}

获取比特币-ZAR价格：

{
  "jsonrpc": "2.0",
  "method": "get_crypto_price",
  "params": {"pair": "XBTZAR"},
  "id": 2
}

发展

项目结构

├── .env                 # Environment variables (API credentials)
├── .gitignore           # Git ignore configuration
├── .vscode/             # VS Code specific settings
│   └── mcp.json         # MCP configuration for VS Code
├── src/                 # Source code
│   ├── main.py          # Entry point
│   └── luno_mcp_server/ # MCP server implementation
│       ├── luno_client.py # Luno API client
│       └── server.py    # MCP server core
├── tests/               # Test suite
├── test_client.py       # Simple test client for the MCP server
├── requirements.txt     # Project dependencies
└── setup.py             # Package setup

运行测试

python -m pytest tests/

添加新功能

要添加新的 Luno API 功能：

使用新的 API 方法扩展src/luno_mcp_server/luno_client.py中的LunoClient类
在src/luno_mcp_server/server.py中的LunoMCPServer类中添加相应的方法
更新server.py中的MCP_METHODS列表，并在_register_methods函数中注册你的方法
在tests/目录中添加测试

建筑学

MCP 服务器采用简单的架构：

JSON-RPC 2.0 用于通信
用于传输的标准输入/输出（STDIO）
用于加密货币操作的 Luno API 客户端

故障排除

常见问题

API 身份验证错误：确保您的 Luno API 密钥在.env文件或.vscode/mcp.json中正确设置
导入错误：确保您已激活虚拟环境
速率限制：Luno API 具有速率限制 - 为生产使用实施重试逻辑

配置优先级

启动服务器时，配置值按以下优先级顺序加载：

通过 MCP 配置传递的环境变量（最高优先级）
.env文件中的值
代码中的默认值（最低优先级）

这意味着您可以在 MCP 配置中设置值来覆盖.env文件中的任何现有值。

多客户端支持

此 MCP 服务器支持通过 WebSocket 同时连接多个客户端。详情请参阅MULTI_CLIENT_SUPPORT.md 。

交通选择

服务器支持两种传输机制：

STDIO （默认）：标准输入/输出 - 单客户端，由 VS Code MCP 使用
WebSockets ：网络传输 - 具有安全功能的多个客户端

使用 WebSockets 传输运行

基本用法：

python -m src.main --transport websocket --host localhost --port 8765

具有安全选项：

python -m src.main --transport websocket --host localhost --port 8765 \
  --max-connections 50 --max-message-size 1048576 --rate-limit 100

使用 SSL/TLS 加密：

# First generate certificates
./generate_certificates.sh

# Then run with SSL support
python -m src.main --transport websocket --ssl-cert ./certs/server.crt --ssl-key ./certs/server.key

WebSocket 客户端工具

该存储库包括两个客户端工具：

test_websocket_client.py ：简单测试客户端
python test_websocket_client.py
enhanced_websocket_client.py ：具有多客户端模拟的高级客户端
# Single client mode python enhanced_websocket_client.py --mode single # Multi-client simulation (3 clients) python enhanced_websocket_client.py --mode multi --clients 3

执照

MIT 许可证

特此授予任何获得该软件和相关文档文件副本的人员免费许可。

Integrations