MCP Mempool

# MCP Mempool 🚀 **비트코인 mempool.space WebSocket & REST API를 위한 Model Context Protocol (MCP) 서버** [](https://docker.com) [](https://python.org) [](https://fastapi.tiangolo.com) [](https://bitcoin.org) ## 📋 개요 MCP Mempool은 mempool.space의 WebSocket과 REST API를 MCP (Model Context Protocol) 형태로 래핑하여 AI Agent와 외부 애플리케이션이 비트코인 네트워크 데이터를 쉽게 활용할 수 있도록 하는 서버입니다. ### ✨ 주요 기능 #### 🔄 WebSocket 기능 (실시간) - **실시간 블록 데이터**: 새 블록 생성 시 즉시 알림 - **멤풀 블록 템플릿**: 예상되는 다음 블록 정보 - **네트워크 통계**: 메모리풀 상태 실시간 모니터링 - **주소 추적**: 특정 비트코인 주소의 거래 실시간 추적 - **라이브 차트**: 수수료 변화 추이 실시간 데이터 #### 🔍 REST API 기능 (쿼리) - **주소 정보 조회**: 잔액, 거래 내역, UTXO 목록 - **거래 정보**: 개별 거래 상세 정보 및 상태 - **블록 데이터**: 블록 정보, 거래 목록, 최신 높이 - **수수료 정보**: 추천 수수료율, 멤풀 블록별 수수료 - **멤풀 상태**: 현재 멤풀 정보 및 최근 거래 - **주소 검증**: 비트코인 주소 유효성 검사 ## 🚀 빠른 시작 ### Docker로 실행 (권장) ```bash # 개발 환경 docker-compose up mcp-mempool-dev # 프로덕션 환경 docker-compose up mcp-mempool-prod ``` 서버가 실행되면 http://localhost:8000 에서 접근 가능합니다. ### 로컬 설치 ```bash # 의존성 설치 uv sync # 서버 실행 uv run python -m mempool_ws_mcp_server.main ``` ## 🔧 환경 변수 설정 ```bash # 서버 설정 MCP_HOST=0.0.0.0 # 서버 호스트 MCP_PORT=8000 # 서버 포트 LOG_LEVEL=INFO # 로그 레벨 # Mempool API 설정 MEMPOOL_WS_URL=wss://mempool.space/api/v1/ws # WebSocket URL MEMPOOL_API_URL=https://mempool.space/api # REST API URL # WebSocket 설정 WS_RECONNECT_INTERVAL=5 # 재연결 간격 (초) WS_MAX_RECONNECT_ATTEMPTS=10 # 최대 재연결 시도 WS_PING_INTERVAL=30 # Ping 간격 (초) WS_PING_TIMEOUT=10 # Ping 타임아웃 (초) # HTTP 클라이언트 설정 HTTP_TIMEOUT=30 # HTTP 요청 타임아웃 (초) HTTP_MAX_RETRIES=3 # 최대 재시도 횟수 # 성능 설정 MAX_MESSAGE_QUEUE_SIZE=1000 # 메시지 큐 최대 크기 MESSAGE_BATCH_SIZE=10 # 메시지 배치 크기 # 보안 설정 CORS_ENABLED=true # CORS 활성화 ALLOWED_ORIGINS=* # 허용된 오리진 (콤마 구분) # 개발 모드 DEBUG=false # 디버그 모드 RELOAD=false # 자동 재시작 ``` ## 🛠 MCP 클라이언트 설정 ### Claude Desktop `claude_desktop_config.json` 파일에 추가: ```json { "mcpServers": { "mcp-mempool": { "command": "npx", "args": ["mcp-remote", "http://localhost:8000/mcp"] } } } { "mcpServers": { "mcp-mempool": { "transport": "streamable-http", "url" : "http://127.0.0.1:8000/mcp" //배포시 실제 서빙 url } } } ``` ### Amazon Q Developer `.aws/amazonq/mcp.json` 파일에 추가: ```json { "mcpServers": { "mcp-mempool": { "command": "npx", "args": ["mcp-remote", "http://localhost:8000/mcp"], "env": { "FASTMCP_LOG_LEVEL": "ERROR" } } } } ``` ## 📡 사용 가능한 도구들 ### WebSocket 도구 (실시간 스트리밍) #### `subscribe_blocks` 새 블록 생성 시 실시간 알림을 받습니다. #### `subscribe_mempool_blocks` 예상되는 다음 블록 템플릿 정보를 실시간으로 받습니다. #### `subscribe_stats` 네트워크 메모리풀 통계를 실시간으로 모니터링합니다. #### `subscribe_live_chart` 2시간 라이브 수수료 차트 데이터를 실시간으로 받습니다. #### `track_address` 특정 비트코인 주소의 거래를 실시간으로 추적합니다. - `address`: 추적할 비트코인 주소 #### `get_connection_status` WebSocket 연결 상태를 확인합니다. #### `unsubscribe_client` 클라이언트의 모든 구독을 해제합니다. - `client_id`: 구독 해제할 클라이언트 ID ### REST API 도구 (쿼리) #### 주소 관련 **`get_address_info`** - 주소의 모든 정보 조회 - `address`: 비트코인 주소 **`get_address_balance`** - 주소 잔액 조회 - `address`: 비트코인 주소 **`get_address_utxos`** - 주소의 UTXO 목록 조회 - `address`: 비트코인 주소 **`get_address_transactions`** - 주소의 거래 내역 조회 - `address`: 비트코인 주소 - `after_txid` (선택): 특정 거래 이후의 거래들만 조회 #### 거래 관련 **`get_transaction_info`** - 거래 정보 조회 - `txid`: 거래 ID **`get_block_info`** - 블록 정보 조회 - `hash_or_height`: 블록 해시 또는 높이 **`get_block_height`** - 현재 블록 높이 조회 #### 수수료 & 멤풀 **`get_recommended_fees`** - 추천 수수료율 조회 **`get_mempool_info`** - 현재 멤풀 정보 조회 #### 유틸리티 **`validate_bitcoin_address`** - 비트코인 주소 유효성 검사 - `address`: 검증할 주소 ## 💻 사용 예시 ### 주소 잔액 조회 ```bash # MCP 클라이언트에서 사용 get_address_balance address="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa" ``` ### 실시간 수수료 모니터링 ```bash # 실시간 멤풀 블록 구독 subscribe_mempool_blocks # 추천 수수료 조회 get_recommended_fees ``` ### 주소 추적 ```bash # 특정 주소 실시간 추적 track_address address="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa" ``` ## 🏗 개발 ### 개발 환경 설정 ```bash # 프로젝트 클론 git clone <repository-url> cd mcp-mempool # 개발 의존성 설치 uv sync --dev # 개발 서버 실행 uv run python -m mempool_ws_mcp_server.main ``` ### 테스트 실행 ```bash # 모든 테스트 실행 uv run pytest # 커버리지 포함 uv run pytest --cov=mempool_ws_mcp_server ``` ### 코드 품질 도구 ```bash # 린팅 uv run ruff check . # 포맷팅 uv run ruff format . # 타입 체크 uv run mypy src/ ``` ## 🐳 Docker 빌드 ```bash # 이미지 빌드 docker build -t mcp-mempool . # 멀티 아키텍처 빌드 docker buildx build --platform linux/amd64,linux/arm64 -t mcp-mempool . ``` ## 📊 모니터링 ```bash # 모니터링 스택 실행 (Prometheus + Grafana) docker-compose --profile monitoring up # Grafana: http://localhost:3000 (admin/admin) # Prometheus: http://localhost:9090 ``` ## 🔗 API 엔드포인트 - **Health Check**: `GET /health` - **Root Info**: `GET /` - **MCP Protocol**: `POST /mcp` - **API Docs**: `GET /docs` ## 📄 라이선스 MIT License ## 🤝 기여 이슈 리포트와 풀 리퀘스트를 환영합니다! ## 📞 지원 - 문제가 있으시면 GitHub Issues를 활용해주세요 - 개선 제안이나 새로운 기능 요청도 환영합니다