MCP 服务器

GoldRush MCP Server

covalenthq

开发者工具

访问服务器

README

GoldRush MCP 服务器

📖 文档

</div>

本项目提供了一个 MCP (模型上下文协议) 服务器，它将 Covalent 的 GoldRush API 作为 MCP 资源和工具公开。它使用 @modelcontextprotocol/sdk 和 @covalenthq/client-sdk 以 TypeScript 实现。

主要特性

模型上下文协议 (MCP) 是一种消息协议，用于将上下文或工具提供服务器与 LLM 客户端连接。此服务器允许 LLM 客户端：

将 Covalent GoldRush API 端点作为 MCP 工具调用
从 MCP 资源读取，这些资源提供链信息、报价货币、链状态等。
使用 Vitest 进行完全测试，以测试每组工具。
模块化架构，其中每个服务都实现为一个单独的模块，从而使代码库更易于维护和扩展。

快速开始

GoldRush API 密钥

使用任何 GoldRush 开发人员工具都需要 API 密钥。请访问 https://goldrush.dev/platform/auth/register/ 获取您的密钥。

与 Claude Desktop 一起使用

将以下内容添加到您的 claude_desktop_config.json：

{
    "mcpServers": {
        "goldrush": {
            "command": "npx",
            "args": ["-y", "@covalenthq/goldrush-mcp-server"],
            "env": {
                "GOLDRUSH_API_KEY": "YOUR_API_KEY_HERE"
            }
        }
    }
}

有关更多详细信息，请遵循官方的 Claude Desktop 用户 MCP 快速入门

与 Claude Code CLI 一起使用

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

有关更多详细信息，请参阅设置模型上下文协议 (MCP)

与 Cursor 一起使用

打开 Cursor 设置
转到 Features > MCP
单击 + Add new global MCP server
将以下内容添加到您的 ~/.cursor/mcp.json：

{
    "mcpServers": {
        "goldrush": {
            "command": "npx",
            "args": ["-y", "@covalenthq/goldrush-mcp-server"],
            "env": {
                "GOLDRUSH_API_KEY": "YOUR_API_KEY_HERE"
            }
        }
    }
}

对于项目特定的配置，请将以上内容添加到项目目录中的 .cursor/mcp.json 文件中。这允许您定义仅在该特定项目中可用的 MCP 服务器。

添加后，刷新 MCP 服务器列表以查看新工具。如果 Composer Agent 确定 MCP 设置页面上“可用工具”下列出的任何 MCP 工具是相关的，它将自动使用它们。要故意提示工具的使用，只需告诉代理使用该工具，可以通过名称或描述来引用它。

请参阅示例 LLM 流程

与 Windsurf 一起使用

将以下内容添加到您的 ~/.codeium/windsurf/mcp_config.json 文件中：

{
    "mcpServers": {
        "goldrush": {
            "command": "npx",
            "args": ["-y", "@covalenthq/goldrush-mcp-server"],
            "env": {
                "GOLDRUSH_API_KEY": "YOUR_API_KEY_HERE"
            }
        }
    }
}

编程方式使用

该服务器旨在由 MCP 客户端作为子进程启动。例如，使用 MCP TypeScript SDK：

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["-y", "@covalenthq/goldrush-mcp-server"],
  env: {"GOLDRUSH_API_KEY"="your_api_key_here"}
});

const client = new Client(
  {
    name: "example-client",
    version: "1.0.0"
  },
  {
    capabilities: {
      tools: {}
    }
  }
);

await client.connect(transport);

// List tools
const resources = await client.listTools();
const tools = await client.listTools();
console.log("Available tools:", tools.tools.map(tool => tool.name).join(", "));

// Now you can call tools
const result = await client.callTool({
    name: "token_balances",
    arguments: {
        chainName: "eth-mainnet",
        address: "demo.eth",
        quoteCurrency: "USD",
        nft: false,
    },
});
console.log("Token balances:", result.content);
...

示例 LLM 流程

基于 LLM 的应用程序启动。
它生成或连接到此 MCP 服务器。
LLM 决定调用一个工具，例如 transaction_summary，以收集有关钱包的数据。
服务器在后台调用 Covalent 端点，将 JSON 返回给 LLM，然后 LLM 在对话上下文中使用它。

工具

工具是模型上下文协议 (MCP) 中的一个强大的原语，它使服务器能够向客户端公开可执行的功能。通过工具，LLM 可以与外部系统交互、执行计算并在现实世界中采取行动。

工具被设计为模型控制的，这意味着工具从服务器公开给客户端，目的是 AI 模型能够自动调用它们（在人工参与批准的情况下）。

bitcoin_hd_wallet_balances
- 获取从 Bitcoin HD 钱包派生的每个活动子地址的余额。此工具提供由 xpub 密钥标识的 Bitcoin 钱包的详细余额数据。必需：walletAddress - HD 钱包的 xpub 密钥。可选：quoteCurrency - 用于价格转换的货币（USD、EUR 等）。返回完整的余额详细信息，包括总余额、可用余额和交易历史记录摘要。
bitcoin_non_hd_wallet_balances
- 获取非 HD 地址的 Bitcoin 余额。响应包括现货价格和其他元数据。此工具提供常规 Bitcoin 地址的详细余额数据。必需：walletAddress - 要查询的 Bitcoin 地址。可选：quoteCurrency - 用于价格转换的货币（USD、EUR 等）。返回完整的余额详细信息，包括总余额、可用余额和交易计数。
bitcoin_transactions
- 获取特定 Bitcoin 地址的交易，其中包含完整的交易详细信息。必需：address - 要查询的 Bitcoin 地址。可选：pageSize - 每页的结果数（默认为 100），pageNumber - 页码（默认为 0）。返回包含时间戳、金额、输入、输出和费用的分页交易列表。
block
- 通常用于获取和呈现区块浏览器的单个区块。需要 chainName（区块链网络）和 blockHeight（区块号）。返回全面的区块数据，包括时间戳、交易计数、大小、矿工信息和其他特定于区块链的详细信息。
block_heights
- 通常用于获取特定日期范围内的所有区块高度。需要 chainName（区块链网络）、startDate（YYYY-MM-DD 格式）和 endDate（YYYY-MM-DD 或“latest”）。可选的分页参数包括 pageSize（默认为 10）和 pageNumber（默认为 0）。返回指定日期范围内的区块高度、时间戳和相关数据，对于历史分析和基于时间的区块链查询非常有用。
erc20_token_transfers
- 通常用于呈现代币的转入和转出，以及地址的历史价格。必需：chainName（区块链网络）、walletAddress（钱包地址）。可选：用于价值转换的 quoteCurrency、用于按特定代币过滤的 contractAddress、用于设置范围的 startingBlock/endingBlock、pageSize（默认为 10）和 pageNumber（默认为 0）。返回包含时间戳、值和交易详细信息的代币转移事件。
gas_prices
- 获取特定网络上不同交易速度的实时 gas 估算值，使用户能够优化交易成本和确认时间。需要 chainName（区块链网络）和 eventType（erc20、nativetokens 或 uniswapv3）。可选参数 quoteCurrency 允许转换为不同的货币（USD、EUR 等）。返回指定事件类型的低、中和高优先级交易的估计 gas 价格。
historical_portfolio_value
- 通常用于呈现地址的每日投资组合余额，按代币细分。必需：chainName（区块链网络）、walletAddress（钱包地址）。可选：用于价值转换的 quoteCurrency、days（要分析的时间范围，默认为 7）。返回投资组合价值时间序列数据，显示指定时间范围内的价值变化。
historical_token_balances
- 通常用于获取地址在给定区块高度或日期持有的历史原生和可替代（ERC20）代币。必需：chainName（区块链网络）、address（钱包地址）。可选：用于价值转换的 quoteCurrency、用于指定时间点的 blockHeight 或 date、nft（包括 NFT，默认为 false）、noNftFetch、noSpam 和 noNftAssetMetadata（所有默认为 true）。返回在指定的历史时间点存在的代币余额。
historical_token_prices
- 通常用于获取日期范围之间代币的历史价格。支持原生代币。必需：chainName（区块链网络）、quoteCurrency（价格货币）、contractAddress（代币合约）、from（开始日期 YYYY-MM-DD）、to（结束日期 YYYY-MM-DD）。可选：pricesAtAsc（设置为 true 以按时间顺序升序排列，默认为 false 以按降序排列）。返回指定时间范围内的历史代币价格。
log_events_by_address
- 通常用于获取从特定合约地址发出的所有事件日志。对于构建检查链上交互的仪表板非常有用。需要 chainName（区块链网络）和 contractAddress（发出事件的地址）。可选参数包括区块范围（startingBlock、endingBlock）和分页设置（pageSize 默认为 10，pageNumber 默认为 0）。返回指定合约的解码事件日志，对于监视特定智能合约活动和分析链上事件非常有用。
log_events_by_topic
- 通常用于获取特定链中所有合约的相同主题哈希的所有事件日志。对于链上发出的事件日志的横截面分析非常有用。需要 chainName（区块链网络）和 topicHash（事件签名哈希）。可选参数包括区块范围（startingBlock、endingBlock）、用于按其他参数过滤的 secondaryTopics 和分页设置（pageSize 默认为 10，pageNumber 默认为 0）。返回与指定主题哈希匹配的解码事件日志，非常适合跟踪区块链上多个合约的特定事件类型。
multichain_address_activity
- 获取所有受支持区块链上的钱包活动摘要。需要 walletAddress。可选参数 testnets（默认为 false）确定是否包括测试网活动。返回链活动的全面摘要，包括交易计数、首次/上次活动时间戳和所有网络上的活动状态。
multichain_balances
- 获取多个区块链上的钱包地址的代币余额。需要 walletAddress。可选参数包括用于指定网络的 chains 数组、用于价值转换的 quoteCurrency、limit（默认为 10）、分页（before）和用于按时间过滤的 cutoffTimestamp。使用此选项可全面了解不同区块链上的代币持有量。
multichain_transactions
- 获取多个区块链上的多个钱包地址的交易。需要 addresses 数组。可选参数包括 chains 数组、分页（before/after）、limit（默认为 10）、用于价值转换的 quoteCurrency 以及包含日志的选项（withLogs、withDecodedLogs）。使用此选项可同时分析不同网络上的交易历史记录。
native_token_balance
- 获取区块链上指定钱包地址的本机代币余额（ETH、BNB、MATIC 等）。必需：chainName（区块链网络）和 walletAddress。可选：用于价值转换的 quoteCurrency 和用于历史查询的 blockHeight。返回详细的余额信息，包括格式化的金额和美元价值。
nft_for_address
- 通常用于获取区块链上特定钱包地址拥有的所有 NFT。对于 NFT 投资组合查看器非常有用。必需：chainName（区块链网络）、walletAddress（钱包地址）。可选：noSpam（排除垃圾邮件 NFT，默认为 true）、noNftAssetMetadata（排除详细元数据，默认为 false）、withUncached（包括未缓存的项目，默认为 false）。返回指定钱包拥有的所有 NFT 的全面列表。
nft_check_ownership
- 通常用于验证集合中 NFT（包括 ERC-721 和 ERC-1155）的所有权。必需：chainName（区块链网络）、walletAddress（钱包地址）、collectionContract（NFT 集合）。可选：traitsFilter（按特征类型过滤）、valuesFilter（按特征值过滤）。返回所有权状态和匹配的 NFT（如果拥有）。
token_approvals
- 通常用于获取按钱包资产的消费者的所有代币合约的批准列表。必需：chainName（区块链网络，例如 eth-mainnet 或 1）、walletAddress（钱包地址，支持 ENS、RNS、Lens Handle 或 Unstoppable Domain）。返回 ERC20 代币批准及其关联的安全风险级别列表。
token_balances
- 通常用于获取地址持有的本机和可替代（ERC20）代币。必需：chainName（区块链网络）、address（钱包地址）。可选：用于价值转换的 quoteCurrency、nft（包括 NFT，默认为 false）、noNftFetch、noSpam 和 noNftAssetMetadata（所有默认为 true）以控制返回的数据。返回详细的代币余额信息，包括现货价格和元数据。
token_holders
- 用于获取指定 ERC20 或 ERC721 代币的当前或历史代币持有者的分页列表。必需：chainName（区块链网络）、tokenAddress（代币合约地址）。可选：用于历史数据的 blockHeight 或 date、用于分页的 pageSize 和 pageNumber。返回持有代币的地址列表，其中包含余额金额和所有权百分比。
transaction
- 通常用于获取和呈现单个交易，包括其解码的日志事件。必需：chainName（区块链网络）、txHash（交易哈希）。可选：quoteCurrency（要转换成的货币，默认为 USD）、noLogs（排除事件日志，默认为 true）、withInternal（包括内部交易，默认为 false）、withState（包括状态更改，默认为 false）、withInputData（包括输入数据，默认为 false）。以下链支持跟踪功能（withInternal、withState、withInputData）：eth-mainnet。返回有关指定交易的全面详细信息。
transactions_for_address
- 通常用于获取和呈现涉及地址的最新交易。必需：chainName（区块链网络）、walletAddress（钱包地址）、page（页码）。可选：quoteCurrency、noLogs、blockSignedAtAsc（按时间顺序排列）。返回指定结果页面的交易。
transactions_for_block
- 通常用于获取区块中的所有交易，包括其解码的日志事件，并进一步标记有趣的钱包或交易。必需：chainName（区块链网络）、blockHeight（区块号或最新）。可选：quoteCurrency、noLogs（排除事件日志）。返回指定区块中的所有交易。
transaction_summary
- 通常用于获取钱包的最早和最新交易以及交易计数。必需：chainName（区块链网络）、walletAddress（钱包地址）。可选：quoteCurrency、withGas（包括 gas 使用统计信息）。返回指定钱包的交易活动摘要。

资源

资源是模型上下文协议 (MCP) 中的一个核心原语，它允许服务器公开可以由客户端读取并用作 LLM 交互上下文的数据和内容。

资源被设计为应用程序控制的，这意味着客户端应用程序可以决定如何以及何时使用它们。不同的 MCP 客户端可能会以不同的方式处理资源。例如：

Claude Desktop 当前要求用户显式选择资源，然后才能使用它们
其他客户端可能会根据启发式方法自动选择资源
某些实现甚至可能允许 AI 模型本身确定要使用哪些资源

GoldRush MCP 服务器公开的资源分为静态和动态类型：

静态资源 (src/resources/staticResources.ts)：
- config://supported-chains
- config://quote-currencies
动态资源 (src/resources/dynamicResources.ts)：
- status://all-chains
- status://chain/{chainName}

动态资源在每次请求时从 Covalent API 获取实时数据，从而确保当前信息。

开发

前提条件

Node.js v18 或更高版本
npm、yarn 或 pnpm
包含有效 GoldRush API 密钥的 GOLDRUSH_API_KEY 环境变量

安装

git clone https://github.com/covalenthq/goldrush-mcp-server.git
cd goldrush-mcp-server
npm install

然后构建：

npm run build

运行 MCP 服务器

# 启动服务器 (运行 dist/index.js)
npm run start

这会在 stdin/stdout 上生成 MCP 服务器。通常，MCP 客户端将连接到服务器。

示例客户端

您可以运行示例客户端，该客户端将通过 STDIO 将服务器作为子进程生成：

npm run example

这会尝试一些 Covalent 调用并打印出响应。

运行测试

npm run test

这将运行涵盖每个服务的整个测试套件。

设置 GOLDRUSH_API_KEY

您必须将 GOLDRUSH_API_KEY 环境变量设置为 Covalent 平台中的有效密钥。例如，在 Linux/macOS 上：

export GOLDRUSH_API_KEY=YOUR_KEY_HERE

或者在 Windows 上：

set GOLDRUSH_API_KEY=YOUR_KEY_HERE

文件布局

goldrush-mcp-server
├── src
│   ├── index.ts                 # Main MCP server entry point
│   ├── services/                # Modular service implementations
│   │   ├── AllChainsService.ts  # Cross-chain service tools
│   │   ├── BalanceService.ts    # Balance-related tools
│   │   ├── BaseService.ts       # Basic blockchain tools
│   │   ├── BitcoinService.ts    # Bitcoin-specific tools
│   │   ├── NftService.ts        # NFT-related tools
│   │   ├── PricingService.ts    # Pricing-related tools
│   │   ├── SecurityService.ts   # Security-related tools
│   │   └── TransactionService.ts# Transaction-related tools
│   ├── resources/               # Resource implementations
│   │   ├── staticResources.ts   # Static configuration resources
│   │   └── dynamicResources.ts  # Dynamic chain status resources
│   ├── utils/                   # Utility functions and constants
│   │   ├── constants.ts         # Shared constants
│   │   └── helpers.ts           # Helper functions
│   └── example-client.ts        # Example LLM client using STDIO transport
├── test
│   ├── AllChainsService.test.ts
│   ├── BalanceService.test.ts
│   ├── BaseService.test.ts
│   ├── BitcoinService.test.ts
│   ├── NftService.test.ts
│   ├── PricingService.test.ts
│   ├── Resources.test.ts
│   ├── SecurityService.test.ts
│   └── TransactionService.test.ts
├── eslint.config.mjs            # ESLint configuration
├── package.json                 # Project dependencies and scripts
├── package-lock.json            # Locked dependencies
├── tsconfig.json                # TypeScript configuration
├── LICENSE                      # MIT license
└── README.md                    # Project documentation

调试

使用 Inspector

https://modelcontextprotocol.io/docs/tools/inspector

npx @modelcontextprotocol/inspector node dist/index.js

贡献

我们欢迎社区的贡献！如果您有建议、改进或要添加的新垃圾邮件合约地址，请打开一个 issue 或提交一个 pull request。请随时查看 <a href="https://github.com/covalenthq/goldrush-mcp-server/issues">issues</a> 页面。

表达你的支持

如果此项目对您有帮助，请给一个 ⭐️！

许可证

本项目已获得 <a href="https://github.com/covalenthq/goldrush-mcp-server/blob/main/LICENSE">MIT</a> 许可。