covalenthq/goldrush-mcp-server

이 프로젝트는 Covalent의 GoldRush API를 MCP (Model Context Protocol) 리소스 및 도구로 노출하는 MCP (Model Context Protocol) 서버를 제공합니다. 이는 @modelcontextprotocol/sdk 및 @covalenthq/client-sdk를 사용하여 TypeScript로 구현되었습니다.

Model Context Protocol (MCP)는 컨텍스트 또는 도구 제공 서버를 LLM 클라이언트와 연결하기 위한 메시지 프로토콜입니다. 이 서버를 통해 LLM 클라이언트는 다음과 같은 작업을 수행할 수 있습니다:

Covalent GoldRush API 엔드포인트를 MCP 도구 (Tools)로 호출
체인 정보, 통화 견적 (quote currencies), 체인 상태 등을 제공하는 MCP 리소스 (Resources) 읽기
유연한 전송 지원 (Flexible Transport Support): STDIO 및 HTTP 전송 방식을 모두 지원하는 통합 서버
명령줄 인터페이스 (Command-line Interface): CLI 인수를 통한 간편한 설정
각 도구 그룹을 테스트하기 위해 Vitest로 완전한 테스트 가능
각 서비스가 별도의 모듈로 구현된 모듈형 아키텍처를 통해 코드베이스 유지 관리 및 확장이 용이함

GoldRush 개발자 도구를 사용하려면 API 키가 필요합니다. https://goldrush.dev/platform/auth/register/ 에서 키를 받으세요.

다음 내용을 claude_desktop_config.json에 추가하세요:

{
"mcpServers": {
"goldrush": {
...

자세한 내용은 Claude Desktop 사용자를 위한 공식 MCP Quickstart를 따르세요.

$ claude mcp add goldrush -e GOLDRUSH_API_KEY=<YOUR_API_KEY_HERE> -- npx -y @covalenthq/goldrush-mcp-server@latest

자세한 내용은 Set up Model Context Protocol (MCP)를 참조하세요.

Cursor Settings 열기
Features > MCP로 이동
- Add new global MCP server 클릭
다음 내용을 ~/.cursor/mcp.json에 추가하세요:

{
"mcpServers": {
"goldrush": {
...

프로젝트별 설정을 위해, 프로젝트 디렉토리의 .cursor/mcp.json 파일에 위 내용을 추가하세요. 이를 통해 특정 프로젝트 내에서만 사용할 수 있는 MCP 서버를 정의할 수 있습니다.

추가한 후에는 MCP 서버 목록을 새로고침하여 새로운 도구(tools)들을 확인하세요. Composer Agent는 MCP 설정 페이지의 'Available Tools' 목록에 있는 MCP 도구들이 관련이 있다고 판단하면 자동으로 사용합니다. 의도적으로 도구 사용을 유도하려면, 도구의 이름이나 설명을 언급하며 에이전트에게 해당 도구를 사용하라고 말하면 됩니다.

LLM 흐름 예시 보기

~/.codeium/windsurf/mcp_config.json 파일에 다음 내용을 추가하세요:

{
"mcpServers": {
"goldrush": {
...

이 서버는 다양한 통합 시나리오를 위해 STDIO 및 HTTP 전송(transports) 방식을 모두 지원합니다:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
const transport = new StdioClientTransport({
...

# HTTP 서버 시작
node dist/index.js --transport http --port 3000

그 다음 HTTP 요청을 보냅니다:

const response = await fetch("http://localhost:3000/mcp", {
method: "POST",
headers: {
...

LLM 기반 애플리케이션이 시작됩니다.
애플리케이션이 이 MCP 서버를 생성하거나 연결합니다.
LLM이 지갑에 대한 데이터를 수집하기 위해 transaction_summary와 같은 도구를 호출하기로 결정합니다.
서버는 내부적으로 Covalent 엔드포인트를 호출하고, LLM에 JSON을 반환하며, LLM은 이를 대화 문맥(conversation context)에서 사용합니다.

도구(Tools)는 Model Context Protocol (MCP)에서 서버가 실행 가능한 기능을 클라이언트에 노출할 수 있게 해주는 강력한 기본 요소(primitive)입니다. 도구를 통해 LLM은 외부 시스템과 상호작용하고, 계산을 수행하며, 현실 세계에서 동작을 수행할 수 있습니다.

도구는 모델 제어(model-controlled) 방식으로 설계되었습니다. 즉, AI 모델이 (승인을 위한 인간의 개입(human in the loop)과 함께) 자동으로 도구를 호출할 수 있도록 의도하여 서버에서 클라이언트로 노출됩니다.

bitcoin_hd_wallet_balances

Bitcoin HD 지갑에서 파생된 각 활성 자식 주소(child address)의 잔액을 가져옵니다. 이 도구는 xpub 키로 식별되는 Bitcoin 지갑에 대한 상세 잔액 데이터를 제공합니다. 필수 항목: walletAddress - HD 지갑의 xpub 키. 선택 항목: quoteCurrency - 가격 변환을 위한 통화 (USD, EUR 등). 총 잔액, 사용 가능 잔액 및 거래 내역 요약을 포함한 전체 잔액 상세 정보를 반환합니다.

bitcoin_non_hd_wallet_balances

비(non)-HD 주소의 Bitcoin 잔액을 가져옵니다. 응답에는 스팟 가격(spot prices) 및 기타 메타데이터가 포함됩니다. 이 도구는 일반 Bitcoin 주소에 대한 상세 잔액 데이터를 제공합니다. 필수 항목: walletAddress - 조회할 Bitcoin 주소. 선택 항목: quoteCurrency - 가격 변환을 위한 통화 (USD, EUR 등). 총 잔액, 사용 가능 잔액 및 거래 횟수를 포함한 전체 잔액 상세 정보를 반환합니다.

bitcoin_transactions

전체 거래 상세 정보와 함께 특정 Bitcoin 주소의 거래 내역을 가져옵니다. 필수 항목: address - 조회할 Bitcoin 주소. 선택 항목: pageSize - 페이지당 결과 수 (기본값 100), pageNumber - 페이지 번호 (기본값 0). 타임스탬프, 금액, 입력(inputs), 출력(outputs) 및 수수료(fees)가 포함된 페이지네이션(paginated)된 거래 목록을 반환합니다.

block

일반적으로 블록 익스플로러(block explorer)를 위해 단일 블록을 가져오고 렌더링하는 데 사용됩니다. chainName (블록체인 네트워크) 및 blockHeight (블록 번호)가 필요합니다. 타임스탬프, 거래 횟수, 크기, 채굴자 정보 및 기타 블록체인 특유의 상세 정보를 포함한 포괄적인 블록 데이터를 반환합니다.

block_heights

일반적으로 특정 날짜 범위 내의 모든 블록 높이(block heights)를 가져오는 데 사용됩니다. chainName (블록체인 네트워크), startDate (YYYY-MM-DD 형식) 및 endDate (YYYY-MM-DD 또는 'latest')가 필요합니다. 선택 가능한 페이지네이션 매개변수에는 pageSize (기본값 10) 및 pageNumber (기본값 0)가 포함됩니다. 지정된 날짜 범위 내 블록의 블록 높이, 타임스탬프 및 관련 데이터를 반환하며, 이는 역사적 분석 및 시간 기반의 블록체인 쿼리에 유용합니다.

erc20_token_transfers

특정 주소의 토큰 입금(transfer-in) 및 출금(transfer-out) 내역을 과거 가격과 함께 표시하는 데 흔히 사용됩니다. 필수 항목: chainName (블록체인 네트워크), walletAddress (지갑 주소). 선택 항목: 가치 변환을 위한 quoteCurrency, 특정 토큰 필터링을 위한 contractAddress, 범위를 설정하기 위한 startingBlock/endingBlock, pageSize (기본값 10) 및 pageNumber (기본값 0). 타임스탬프, 값 및 트랜잭션(transaction) 세부 정보가 포함된 토큰 전송 이벤트를 반환합니다.

gas_prices

특정 네트워크에서 다양한 트랜잭션 속도에 대한 실시간 가스(gas) 추정치를 가져와, 사용자가 트랜잭션 비용과 확정 시간을 최적화할 수 있도록 합니다. chainName (블록체인 네트워크) 및 eventType (erc20, nativetokens 또는 uniswapv3)이 필요합니다. 선택적 파라미터인 quoteCurrency를 통해 다른 통화(USD, EUR 등)로 변환할 수 있습니다. 지정된 이벤트 유형에 대해 낮음, 중간, 높음 우선순위 트랜잭션에 대한 예상 가스 가격을 반환합니다.

historical_portfolio_value

특정 주소의 일일 포트폴리오 잔액을 토큰별로 나누어 표시하는 데 흔히 사용됩니다. 필수 항목: chainName (블록체인 네트워크), walletAddress (지갑 주소). 선택 항목: 가치 변환을 위한 quoteCurrency, days (분석할 기간, 기본값 7). 지정된 기간 동안의 가치 변화를 보여주는 포트폴리오 가치 시계열 데이터를 반환합니다.

historical_token_balances

특정 블록 높이(block height) 또는 날짜에 주소가 보유했던 과거의 네이티브(native) 및 대체 가능(fungible, ERC20) 토큰을 가져오는 데 흔히 사용됩니다. 필수 항목: chainName (블록체인 네트워크), address (지갑 주소). 선택 항목: 가치 변환을 위한 quoteCurrency, 특정 시점을 지정하기 위한 blockHeight 또는 date, nft (NFT 포함 여부, 기본값 false), noNftFetch, noSpam, 그리고 noNftAssetMetadata (모두 기본값 true). 지정된 과거 시점에 존재했던 토큰 잔액을 반환합니다.

historical_token_prices

날짜 범위 내 토큰의 과거 가격을 가져오는 데 흔히 사용됩니다. 네이티브 토큰 (native tokens)을 지원합니다. 필수 항목: chainName (블록체인 네트워크), quoteCurrency (가격 통화), contractAddress (토큰 컨트랙트), from (시작 날짜 YYYY-MM-DD), to (종료 날짜 YYYY-MM-DD). 선택 항목: pricesAtAsc (true로 설정 시 시간순 오름차순, 기본값은 내림차순을 위한 false). 지정된 시간 범위에 대한 과거 토큰 가격을 반환합니다.

log_events_by_address

특정 컨트랙트 주소 (contract address)에서 발생한 모든 이벤트 로그 (event logs)를 가져오는 데 흔히 사용됩니다. 온체인 (on-chain) 상호작용을 조사하는 대시보드를 구축하는 데 유용합니다. 필수 항목: chainName (블록체인 네트워크) 및 contractAddress (이벤트를 발생시키는 주소). 선택 항목에는 블록 범위 (startingBlock, endingBlock) 및 페이지네이션 (pagination) 설정 (pageSize 기본값 10, pageNumber 기본값 0)이 포함됩니다. 지정된 컨트랙트에 대한 디코딩된 이벤트 로그를 반환하며, 특정 스마트 컨트랙트 (smart contract) 활동을 모니터링하고 온체인 이벤트를 분석하는 데 유용합니다.

log_events_by_topic

특정 체인 내의 모든 컨트랙트에 걸쳐 동일한 토픽 해시 (topic hash)를 가진 모든 이벤트 로그를 가져오는 데 흔히 사용됩니다. 온체인에서 발생하는 이벤트 로그의 횡단면 분석 (cross-sectional analysis)에 유용합니다. 필수 항목: chainName (블록체인 네트워크) 및 topicHash (이벤트 시그니처 해시). 선택 항목에는 블록 범위 (startingBlock, endingBlock), 추가 파라미터로 필터링하기 위한 secondaryTopics, 그리고 페이지네이션 (pagination) 설정 (pageSize 기본값 10, pageNumber 기본값 0)이 포함됩니다. 지정된 토픽 해시와 일치하는 디코딩된 이벤트 로그를 반환하며, 블록체인 상의 여러 컨트랙트에 걸쳐 특정 이벤트 유형을 추적하는 데 이상적입니다.

multichain_address_activity

지원되는 모든 블록체인에 걸친 지갑 활동 요약을 가져옵니다. walletAddress가 필요합니다. 선택 항목인 testnets (기본값 false)는 테스트넷 활동 포함 여부를 결정합니다. 모든 네트워크에 걸친 트랜잭션 횟수, 최초/최종 활동 타임스탬프, 활동 상태를 포함한 체인 활동의 종합적인 요약을 반환합니다.

multichain_balances

여러 블록체인(blockchains)에 걸친 특정 지갑 주소(wallet address)의 토큰 잔액을 가져옵니다. walletAddress가 필요합니다. 선택적 파라미터로는 네트워크를 지정하는 chains 배열, 가치 변환을 위한 quoteCurrency, limit (기본값 10), 페이지네이션(pagination)을 위한 before, 그리고 시간 필터링을 위한 cutoffTimestamp가 있습니다. 이를 사용하여 서로 다른 블록체인에 걸친 토큰 보유 현황을 종합적으로 파악할 수 있습니다.

multichain_transactions

여러 블록체인에 걸친 여러 지갑 주소의 트랜잭션(transactions)을 가져옵니다. addresses 배열이 필요합니다. 선택적 파라미터로는 chains 배열, 페이지네이션(before/after), limit (기본값 10), 가치 변환을 위한 quoteCurrency, 그리고 로그 포함 옵션(withLogs, withDecodedLogs)이 있습니다. 이를 사용하여 서로 다른 네트워크의 트랜잭션 내역을 동시에 분석할 수 있습니다.

native_token_balance

블록체인 상의 특정 지갑 주소에 대한 네이티브 토큰(native token) 잔액(ETH, BNB, MATIC 등)을 가져옵니다. 필수 항목: chainName (블록체인 네트워크) 및 walletAddress. 선택적 항목: 가치 변환을 위한 quoteCurrency 및 과거 쿼리를 위한 blockHeight. 포맷팅된 금액과 USD 가치를 포함한 상세 잔액 정보를 반환합니다.

nft_check_ownership

컬렉션 내에서 NFT(ERC-721 및 ERC-1155 포함)의 소유권을 확인하는 데 주로 사용됩니다. 필수 항목: chainName (블록체인 네트워크), walletAddress (지갑 주소), collectionContract (NFT 컬렉션). 선택적 항목: traitsFilter (특성 유형별 필터링), valuesFilter (특성 값별 필터링). 소유 상태와 소유 중인 경우 일치하는 NFT를 반환합니다.

nft_for_address

블록체인 상의 특정 지갑 주소가 소유한 모든 NFT를 가져오는 데 주로 사용됩니다. NFT 포트폴리오 뷰어에 유용합니다. 필수 항목: chainName (블록체인 네트워크), walletAddress (지갑 주소). 선택적 항목: noSpam (스팸 NFT 제외, 기본값 true), noNftAssetMetadata (상세 메타데이터 제외, 기본값 false), withUncached (캐시되지 않은 항목 포함, 기본값 false). 지정된 지갑이 소유한 모든 NFT의 종합적인 목록을 반환합니다.

pool_spot_prices

지정된 풀 컨트랙트 주소(pool contract address)에 대한 스팟 토큰 쌍 가격(spot token pair prices)을 가져옵니다. Uniswap V2, V3 및 그 포크(fork)된 풀들을 지원합니다. 필수 항목: chainName (블록체인 네트워크), contractAddress (풀 컨트랙트 주소). 선택 항목: 가치 변환을 위한 quoteCurrency (가격 통화). 풀 상세 정보 및 토큰 메타데이터(metadata)와 함께 스팟 토큰 쌍 가격을 반환합니다.

token_approvals

지갑 자산에 대해 지출자(spender)별로 분류된 모든 토큰 컨트랙트의 승인(approval) 목록을 가져오는 데 흔히 사용됩니다. 필수 항목: chainName (블록체인 네트워크, 예: eth-mainnet 또는 1), walletAddress (지갑 주소, ENS, RNS, Lens Handle 또는 Unstoppable Domain 지원). ERC20 토큰 승인 목록과 그와 관련된 보안 위험 수준(security risk levels)을 반환합니다.

token_balances

주소가 보유한 네이티브(native) 및 대체 가능(fungible, ERC20) 토큰을 가져오는 데 흔히 사용됩니다. 필수 항목: chainName (블록체인 네트워크), address (지갑 주소). 선택 항목: 가치 변환을 위한 quoteCurrency, nft (NFT 포함 여부, 기본값 false), noNftFetch, noSpam, noNftAssetMetadata (모두 기본값 true)는 반환되는 데이터를 제어합니다. 스팟 가격(spot prices) 및 메타데이터를 포함한 상세 토큰 잔액 정보를 반환합니다.

token_holders

covalenthq/goldrush-mcp-server

요약

핵심 포인트

댓글