MCP Mempool 🚀

비트코인 mempool.space WebSocket & REST API를 위한 Model Context Protocol (MCP) 서버

📋 개요

MCP Mempool은 mempool.space의 WebSocket과 REST API를 MCP (Model Context Protocol) 형태로 래핑하여 AI Agent와 외부 애플리케이션이 비트코인 네트워크 데이터를 쉽게 활용할 수 있도록 하는 서버입니다.

✨ 주요 기능

🔄 WebSocket 기능 (실시간)

• 실시간 블록 데이터: 새 블록 생성 시 즉시 알림
• 멤풀 블록 템플릿: 예상되는 다음 블록 정보
• 네트워크 통계: 메모리풀 상태 실시간 모니터링
• 주소 추적: 특정 비트코인 주소의 거래 실시간 추적
• 라이브 차트: 수수료 변화 추이 실시간 데이터

🔍 REST API 기능 (쿼리)

• 주소 정보 조회: 잔액, 거래 내역, UTXO 목록
• 거래 정보: 개별 거래 상세 정보 및 상태
• 블록 데이터: 블록 정보, 거래 목록, 최신 높이
• 수수료 정보: 추천 수수료율, 멤풀 블록별 수수료
• 멤풀 상태: 현재 멤풀 정보 및 최근 거래
• 주소 검증: 비트코인 주소 유효성 검사

🚀 빠른 시작

Docker로 실행 (권장)

# 개발 환경
docker-compose up mcp-mempool-dev

# 프로덕션 환경  
docker-compose up mcp-mempool-prod

서버가 실행되면 http://localhost:8000 에서 접근 가능합니다.

로컬 설치

# 의존성 설치
uv sync

# 서버 실행
uv run python -m mempool_ws_mcp_server.main

🔧 환경 변수 설정

# 서버 설정
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 파일에 추가:

{
  "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 파일에 추가:

{
  "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: 검증할 주소

💻 사용 예시

주소 잔액 조회

# MCP 클라이언트에서 사용
get_address_balance address="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"

실시간 수수료 모니터링

# 실시간 멤풀 블록 구독
subscribe_mempool_blocks

# 추천 수수료 조회
get_recommended_fees

주소 추적

# 특정 주소 실시간 추적
track_address address="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"

🏗 개발

개발 환경 설정

# 프로젝트 클론
git clone <repository-url>
cd mcp-mempool

# 개발 의존성 설치
uv sync --dev

# 개발 서버 실행
uv run python -m mempool_ws_mcp_server.main

테스트 실행

# 모든 테스트 실행
uv run pytest

# 커버리지 포함
uv run pytest --cov=mempool_ws_mcp_server

코드 품질 도구

# 린팅
uv run ruff check .

# 포맷팅
uv run ruff format .

# 타입 체크
uv run mypy src/

🐳 Docker 빌드

# 이미지 빌드
docker build -t mcp-mempool .

# 멀티 아키텍처 빌드
docker buildx build --platform linux/amd64,linux/arm64 -t mcp-mempool .

📊 모니터링

# 모니터링 스택 실행 (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를 활용해주세요
• 개선 제안이나 새로운 기능 요청도 환영합니다