루노 MCP 서버

Luno 암호화폐 거래소 API를 위한 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버는 AI 모델과 애플리케이션이 암호화폐 거래를 위해 Luno API와 상호 작용할 수 있도록 표준화된 인터페이스를 제공합니다.

지엑스피1

특징

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를 사용하여 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

AI 어시스턴트와 함께 사용

Docker 컨테이너를 시작한 후 다양한 AI 어시스턴트를 연결하여 Luno MCP 서버를 사용할 수 있습니다.

커서

커서 구성에 다음을 추가하세요.

{
  "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 프로토콜 통합

이 서버는 AI 모델이 표준화된 JSON-RPC 2.0 메시지를 통해 상호 작용할 수 있도록 하는 모델 컨텍스트 프로토콜(Model Context Protocol)을 구현합니다. 이 서버는 기본적으로 STDIO를 통해 작동하므로 VS Code 확장 프로그램 및 기타 MCP 호환 클라이언트와 쉽게 통합할 수 있습니다.

VS 코드 통합

.vscode/mcp.json 파일은 VS Code에서 사용할 서버를 구성합니다. 두 가지 서버 구성이 제공됩니다.

luno-mcp-server-stdio - STDIO 전송을 사용합니다(기본 MCP 동작)
luno-mcp-server-websocket - 여러 클라이언트 지원을 위해 WebSocket 전송을 사용합니다.

VS 코드 구성

VS Code에서 WebSocket 전송을 사용하려면 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 기능을 추가하려면:

src/luno_mcp_server/luno_client.py 에서 새로운 API 메서드를 사용하여 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 서버는 웹소켓을 통해 여러 클라이언트의 동시 연결을 지원합니다. 자세한 내용은 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
improved_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