/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}
1. 项目概述：一个连接加密世界与AI的桥梁
如果你正在开发一个需要实时获取加密货币价格、交易数据、钱包余额，甚至执行链上交易的AI应用，那么你很可能正面临一个棘手的集成问题。传统的做法是直接调用各大交易所或区块链节点的API，但这意味着你要处理不同链的RPC节点、管理API密钥、处理速率限制和错误重试，更别提那些复杂的Web3库和钱包签名逻辑了。整个过程繁琐、脆弱，且难以维护。
CryptoAPIs-io/cryptoapis-mcp-shared
这个项目，就是为了解决这个痛点而生的。它本质上是一个
“模型上下文协议”
共享服务器，专门为
CryptoAPIs
这家区块链数据服务商打造。简单来说，它把 CryptoAPIs 提供的上百种区块链数据和服务，打包成了一个标准化、统一的接口，让像 Claude、Cursor 这类支持 MCP 协议的 AI 助手和开发工具，能够像调用本地函数一样，轻松地获取加密数据或执行链上操作。
想象一下，你可以在 AI 编码助手的聊天框里直接问：“帮我查一下以太坊主网上这个地址（0x…）的 USDT 余额”，或者命令它：“给这个地址转 0.01 个测试网的 ETH”，AI 助手能理解你的意图，并通过这个 MCP 服务器自动完成所有复杂的后端调用，最后把清晰的结果返回给你。这不仅仅是省去了你手动查文档、写代码的时间，更是将区块链能力无缝地编织进了你的开发工作流和思考过程中。这个项目适合任何希望将区块链数据能力集成到 AI 驱动工具中的开发者、数据分析师以及 DeFi 协议团队。
2. 核心架构与 MCP 协议深度解析
2.1 什么是 MCP？为什么它是关键
MCP，全称 Model Context Protocol，是由 Anthropic 公司提出并开源的一种协议。它的核心目标是解决大语言模型的一个根本性短板：模型本身的知识是静态的、过时的，并且无法直接执行操作。MCP 定义了一套标准，允许外部服务器（称为 MCP 服务器）向客户端（如 Claude Desktop、Cursor 等）动态地“暴露”一系列工具（Tools）和资源（Resources）。
你可以把 MCP 服务器想象成一个“技能插件库”。AI 客户端通过 MCP 协议连接到这个服务器后，就能立刻获得服务器提供的所有新能力。对于
cryptoapis-mcp-shared
而言，它提供的“技能”就是与区块链交互的一切：查询数据、读取合约、发送交易。
这种架构带来了几个革命性优势：
安全性隔离
：私钥、API Key 等敏感信息完全存储在本地或你信任的 MCP 服务器环境中，不会泄露给 AI 服务提供商。AI 客户端只是发起请求的“指挥官”，真正执行危险操作的是你本地可控的服务器。
能力动态扩展
：无需等待 AI 模型本身更新或训练。任何新的区块链或新的 API 方法，只要在 MCP 服务器上实现，就能立即被所有连接的 AI 工具使用。
标准化接口
：无论底层是调用 CryptoAPIs 的 REST API，还是直接连接一个以太坊节点，抑或是调用 AWS 的托管服务，暴露给 AI 客户端的工具接口都是统一的。这极大地降低了 AI 工具开发的复杂度。
2.2 CryptoAPIs MCP 服务器的组件拆解
这个共享的 MCP 服务器实现，通常包含以下几个核心组件：
协议适配层
：这是项目的核心。它需要实现 MCP 协议规定的标准接口，特别是
listTools
、
callTool
和
listResources
。当 AI 客户端连接时，它通过
listTools
获取所有可用的工具列表，比如
get_eth_balance
,
broadcast_transaction
等。
CryptoAPIs 客户端封装层
：这一层负责与 CryptoAPIs 的后端服务进行通信。CryptoAPIs 本身提供了一个功能强大的统一 API，支持比特币、以太坊、波卡等数十条主流区块链。封装层需要根据配置的 API Key，构造正确的 HTTP 请求，处理认证，并格式化返回数据。
工具定义与实现
：这是业务逻辑所在。每个工具都是一个独立的函数，它需要：
-
定义输入参数
：例如，
get_token_balance
工具需要
blockchain
(字符串)、
network
(字符串)、
address
(字符串)、
tokenIdentifier
(字符串) 等参数。
-
实现调用逻辑
：将输入参数映射到 CryptoAPIs 特定的 API 端点，发起调用。
-
处理与格式化响应
：将 CryptoAPIs 返回的、可能很复杂的 JSON 数据，提炼、转换成对 AI 助手友好、易于理解和呈现的格式（通常是简洁的文本或结构化数据）。
配置与凭证管理
：服务器需要安全地读取用户的 CryptoAPIs API Key，可能还有特定网络的 RPC URL 或钱包信息。这些配置通常通过环境变量或配置文件来管理，确保不会硬编码在代码中。
注意
：项目的“shared”后缀可能意味着它提供了一个基础、可复用的框架或模板，你需要根据自身需求进行配置和扩展，而不是一个开箱即用、无需配置的全球服务。
3. 核心功能与实操场景全览
这个 MCP 服务器所能提供的工具集，直接反映了 CryptoAPIs 服务的能力范围。我们可以将其分为四大类功能，每一类都对应着丰富的实操场景。
3.1 区块链数据查询：AI 成为你的实时链上分析师
这是最常用的一类功能。AI 助手可以替你执行复杂的链上数据检索，你只需用自然语言描述需求。
-
工具示例
：
get_address_balance
,
get_transaction
,
get_block
,
get_token_metadata
。
-
实操场景
：
-
尽职调查
：在投资或与某个 DeFi 协议交互前，让 AI 查询协议金库地址的资金流向和持仓变化。
-
监控预警
：你可以设定一个思维链，让 AI 定期检查特定地址的大额转账，一旦发生就通知你。
-
数据看板
：快速为你的项目或关注的投资组合拉取实时数据，如总锁仓量、代币价格、交易量，而无需离开编码环境或聊天界面。
-
-
实操要点
：
-
参数准确性
：区块链和网络名称必须与 CryptoAPIs 支持的标识完全一致（如
ethereum-mainnet
,
bitcoin-testnet
）。这是最常见的调用失败原因。
-
数据新鲜度
：理解不同查询的“最终性”。余额查询通常是近乎实时的，而获取一个刚出块的交易详情可能会有几秒延迟。
-
费率限制
：注意 CryptoAPIs 套餐的请求速率限制。在 AI 高频交互场景下，可能需要实现简单的请求队列或缓存机制来避免超额。
-
3.2 交易广播与状态跟踪：让 AI 协助执行链上操作
这是更进阶的能力，允许 AI 助手协助你构建和发送交易。
-
工具示例
：
broadcast_transaction
(广播已签名的原始交易),
get_transaction_receipt
。
-
实操场景
：
-
自动化测试
：在开发智能合约时，让 AI 助手帮你向测试网发送一系列复杂的交易来验证合约逻辑。
-
批量操作
：虽然 AI 不能直接管理私钥签名，但你可以让它为你生成一系列待签名的交易数据，然后你统一签名后，再通过它批量广播。
-
交易状态跟踪
：发送交易后，直接问 AI：“我刚发的那个交易确认了吗？”它调用工具获取回执，告诉你确认数、状态（成功/失败）以及 Gas 消耗。
-
-
实操要点
：
-
安全边界
：必须极其明确，
MCP 服务器本身不应存储或接触私钥
。签名操作必须在完全离线的安全环境（如硬件钱包、本地脚本）中完成。MCP 服务器只处理已签名的、十六进制格式的原始交易数据。
-
网络选择
：广播交易时，务必再三确认网络是测试网而非主网，避免资产损失。
-
错误处理
：交易可能因 Gas 不足、nonce 错误等原因失败。AI 返回的错误信息需要清晰，能指导你进行下一步操作（如调整 Gas、重设 nonce）。
-
3.3 智能合约交互：无需深究 ABI 的查询
对于只读的智能合约调用，MCP 服务器可以封装这一过程。
-
工具示例
：
call_contract_view_method
(调用合约的 view/pure 函数)。
-
实操场景
：
-
代币信息查询
：查询某个 LP 池子的储备量、某个 NFT 合约的总供应量、某个地址在治理合约中的投票权权重。
-
价格获取
：直接从 Chainlink 预言机或其他价格合约中读取最新价格。
-
协议状态检查
：查询借贷协议的抵押率、保险库的存款利率等。
-
-
实操要点
：
-
函数签名与参数编码
：这是最大的难点。你需要准确知道合约函数的 ABI 签名（如
balanceOf(address)
）和参数如何编码。通常，这个工具需要你传入函数签名和编码后的参数十六进制字符串。更好的实现可能会尝试简化这个过程，例如允许传入参数类型和值的列表，由服务器端辅助编码。
-
区块链一致性
：确保你查询的合约地址和函数存在于你指定的区块链和网络上。
-
3.4 资源（Resources）提供：静态数据的注入
除了动态工具，MCP 还支持“资源”。资源可以看作是静态或半静态的上下文信息，AI 客户端可以在会话开始时或按需加载。
-
资源示例
：
supported_blockchains.json
(CryptoAPIs 支持的区块链列表),
common_token_addresses.md
(常见代币合约地址簿)。
-
实操场景
：当 AI 助手刚连接到服务器时，自动加载
supported_blockchains.json
。这样，当你提出“查询比特币余额”时，AI 已经知道该使用哪个正确的区块链标识符（
bitcoin-mainnet
），而不是盲目猜测或要求你澄清。
-
实操要点
：合理设计资源内容，避免过大。资源应是那些不常变化、但对工具正确使用至关重要的参考数据。
4. 从零开始：部署与配置你的私有 MCP 服务器
假设你想基于这个共享项目，搭建一个自己私有的、连接到 CryptoAPIs 的 MCP 服务器。以下是详细的步骤和心路历程。
4.1 环境准备与依赖安装
首先，你需要一个基本的 Node.js/Python 或 Go 环境（具体取决于项目实现语言，这里以常见的 Node.js 为例）。
# 1. 克隆仓库
git clone https://github.com/CryptoAPIs-io/cryptoapis-mcp-shared.git
cd cryptoapis-mcp-shared
# 2. 安装依赖（假设是 Node.js 项目）
npm install
# 3. 检查项目结构
ls -la
你通常会看到类似这样的结构：
-
src/
：源代码目录，包含
server.js
（主服务器文件）、
tools/
（各个工具的实现）、
clients/
（CryptoAPIs 客户端）。
-
package.json
：项目依赖和脚本定义。
-
.env.example
：环境变量示例文件。
-
README.md
：项目说明。
4.2 获取并配置 CryptoAPIs 密钥
cp .env.example .env
.env
文件：
CRYPTOAPIS_API_KEY=your_api_key_here
# 可能还有其他配置，如默认区块链网络、日志级别等
MCP_SERVER_PORT=3000 # MCP 服务器监听的端口
安全警告
：务必确保
.env
文件被添加到
.gitignore
中，绝对不要将包含真实 API Key 的配置文件提交到公开版本库。
4.3 运行服务器并与 AI 客户端连接
启动服务器
：
npm start
# 或如果配置了开发模式
npm run dev
如果一切正常，终端会输出类似
MCP Server running on stdio
或
Server listening on port 3000
的信息。MCP 服务器通常通过标准输入输出（stdio）与客户端通信，这是为了与 Claude Desktop 等工具深度集成。
配置 AI 客户端（以 Claude Desktop 为例）
：
-
找到 Claude Desktop 的配置文件位置（通常在
~/Library/Application Support/Claude/claude_desktop_config.json
或类似路径）。
- 在配置文件中添加你的 MCP 服务器配置。配置方式取决于服务器是作为本地进程启动还是通过 SSH 连接。
-
本地进程配置示例
：
{
"mcpServers": {
"cryptoapis": {
"command": "node",
"args": ["/absolute/path/to/your/cryptoapis-mcp-shared/src/server.js"],
"env": {
"CRYPTOAPIS_API_KEY": "your_api_key_here"
}
}
}
} - 保存配置并重启 Claude Desktop。
验证连接
：
- 重启后，在 Claude 的聊天界面，你应该能直接使用新功能。可以尝试提问：“列出你有哪些可用的工具？”或者“帮我查一下以太坊主网上 vitalik.eth 的 ETH 余额。”（如果集成了 ENS 解析工具）。
5. 高级应用：自定义工具开发与集成
开源项目的魅力在于可扩展性。
cryptoapis-mcp-shared
很可能提供了一个清晰的框架，让你能够添加自己业务所需的特定工具。
5.1 如何添加一个自定义查询工具
假设 CryptoAPIs 提供了一个新的 API，用于获取某个 DeFi 协议的历史 APR 数据，而项目尚未集成。你可以自行添加。
在
src/tools/
目录下创建新文件
，例如
get_defi_apr.js
。
遵循现有工具的模式
，导出一个符合 MCP 工具定义的对象：
// get_defi_apr.js
const { makeTool } = require('../utils/mcp-utils'); // 假设有这样一个工具创建辅助函数
const cryptoApisClient = require('../clients/cryptoapis');
const getDefiAprTool = makeTool({
name: 'get_defi_apr',
description: '获取指定 DeFi 池子的历史年化收益率数据。',
inputSchema: {
type: 'object',
properties: {
blockchain: { type: 'string', description: '区块链，如 ethereum' },
network: { type: 'string', description: '网络，如 mainnet' },
poolAddress: { type: 'string', description: '流动性池合约地址' },
timeframe: { type: 'string', enum: ['7d', '30d', '90d'], description: '时间范围' }
},
required: ['blockchain', 'network', 'poolAddress']
},
execute: async ({ blockchain, network, poolAddress, timeframe = '7d' }) => {
// 1. 调用 CryptoAPIs 的特定端点
const response = await cryptoApisClient.get(`/defi/apr`, {
params: { blockchain, network, poolAddress, timeframe }
});
// 2. 处理响应，提取和格式化关键数据
const data = response.data;
const averageApr = data.averageApr;
const chartData = data.history; // 假设返回历史数据点
// 3. 返回对 AI 友好的结果
return {
content: [{
type: 'text',
text: `池子 ${poolAddress} 在过去 ${timeframe} 的平均 APR 为 ${averageApr}%。历史趋势数据已获取。`
// 可以附加更结构化的数据供 AI 进一步分析
}]
};
}
});
module.exports = getDefiAprTool;
在主服务器文件（如
src/server.js
）中注册这个新工具
，将其添加到工具列表中。
重启 MCP 服务器
。现在，你的 AI 助手就拥有了这个全新的、定制化的数据查询能力。
5.2 集成其他数据源或服务
MCP 服务器的设计是开放的。你完全可以不局限于 CryptoAPIs。你可以在同一个服务器实例中，集成多个数据源。
-
混合数据源
：对于 CryptoAPIs 不支持的某些新兴链或特定数据，你可以编写工具，直接调用该链的公共 RPC 节点，或者调用 The Graph 的子图查询。
-
聚合与计算
：你可以创建更复杂的工具，例如
compare_dex_prices
。这个工具的内部逻辑可能是：并行调用多个工具或数据源（通过 CryptoAPIs 获取 Uniswap 价格，通过直接 RPC 调用获取 Sushiswap 价格），然后计算价差，最后返回一个聚合分析结果。
-
工作流自动化
：结合 AI 的推理能力，你可以设计链式工具调用。例如，AI 可以先调用
get_token_price
检查价格，如果价格合适，再引导你（或在你确认后）调用
prepare_swap_transaction
工具生成交易数据。
6. 常见问题、故障排查与性能优化
在实际部署和使用中，你肯定会遇到各种问题。以下是一些典型场景和解决思路。
6.1 连接与认证问题
| AI 客户端无法连接服务器，提示超时或连接拒绝。 |
1. MCP 服务器进程未成功启动。
2. 客户端配置的命令或路径错误。 3. 端口冲突或防火墙阻止。 |
1. 检查服务器终端是否有错误日志。确保依赖已安装 (
npm install )。 2. 逐字核对 Claude Desktop 配置文件中的 command 和 args ，使用绝对路径。 3. 尝试在命令行直接运行配置的命令，看是否能启动。 |
| 连接成功，但调用工具时返回“认证失败”或“无效 API Key”。 |
1.
.env 文件中的 CRYPTOAPIS_API_KEY 未正确设置或加载。 2. API Key 已失效或被禁用。 3. 服务器代码中读取环境变量的方式有误。 |
1. 在服务器代码启动后，立即打印环境变量值进行确认。
2. 登录 CryptoAPIs 控制台，确认 Key 状态是否正常，是否有使用量或权限限制。 3. 检查服务器代码，确保在调用 CryptoAPIs 客户端前，环境变量已注入。 |
6.2 工具调用与数据问题
| 调用工具时，AI 返回“工具参数错误”或“未知工具”。 |
1. 工具名称拼写错误。
2. 传入的参数格式或类型不符合工具定义的模式（schema）。 3. 所需的参数缺失。 |
1. 让 AI 列出所有可用工具，核对名称。
2. 仔细阅读工具的 description 和 inputSchema 。确保 blockchain 、 network 等字符串值与 CryptoAPIs 文档完全一致。 3. 使用 AI 客户端的调试功能（如果有），查看原始请求和响应。 |
| 查询结果返回慢，或频繁出现速率限制错误。 |
1. CryptoAPIs 免费套餐的速率限制较低。
2. 服务器或网络延迟高。 3. 工具内部逻辑复杂，或未做缓存。 |
1. 升级 CryptoAPIs 套餐，或优化请求频率。在工具实现中加入延迟和重试逻辑。
2. 为不常变的数据（如代币元数据）实现内存缓存（如 node-cache）。 3. 考虑将多个关联查询合并成一个更高效的工具调用。 |
| 交易广播失败，提示“insufficient funds”或“nonce too low”。 |
1. 发送地址余额不足支付 Gas 费和转账金额。
2. Nonce 值设置不正确，低于链上当前记录的值。 3. 交易数据格式错误。 |
1.
广播前务必先查询余额 。让 AI 调用余额查询工具进行确认。 2. 实现或使用一个 get_next_nonce 工具，在构建交易前动态获取地址的最新 nonce。 3. 对于复杂合约交互，先在测试网上充分验证交易数据的正确性。 |
6.3 安全与运维考量
权限最小化
：在 CryptoAPIs 控制台，如果支持，为你的 API Key 创建细粒度的权限策略。例如，如果某个 MCP 服务器实例只用于查询，那就只授予其“只读”权限，绝不授予发送交易的权限。
日志与审计
：为你的 MCP 服务器启用详细的日志记录，记录谁（通过哪个客户端）在什么时间调用了什么工具、使用了哪些参数。这对于调试和安全性审计至关重要。
进程管理
：如果你将 MCP 服务器部署在远程服务器上并通过 SSH 连接，需要使用像
systemd
或
pm2
这样的进程管理工具来保证其稳定运行，并在崩溃后自动重启。
依赖更新
：定期更新项目依赖，特别是 CryptoAPIs SDK 和任何安全相关的库，以修补潜在漏洞。
7. 个人实践心得与进阶建议
经过一段时间的实际搭建和使用，我发现将区块链能力通过 MCP 注入 AI 工作流，其价值远超简单的“查余额”。它改变了我和链上数据、智能合约交互的方式。
最大的体会是“交互范式的转变”
。以前，我需要打开区块浏览器、查阅 API 文档、编写并运行脚本。现在，很多探索性的、一次性的查询，我直接在 Claude 的聊天窗口里用自然语言完成。比如，在分析一个空投机会时，我可以连续发问：“这个项目的代币分配合约是哪个？”、“查一下这个合约过去一周的大额转账记录”、“计算下国库地址的资产构成”。AI 像一位不知疲倦的研究助理，替我完成了所有繁琐的 API 调用和数据初步整理。
关于性能，一个关键的技巧是“预加载上下文”
。我修改了服务器，在连接建立时，不仅提供
supported_blockchains
资源，还会加载一个我经常关注的“地址簿”资源（包含我自己的地址、常用协议合约地址等）。这样，当我提到“我的主地址”时，AI 能直接映射到具体的 0x… 地址，交互更加流畅。
对于想深入开发的同行，我的建议是：
从“只读”工具开始
：先完美实现所有数据查询类工具。这是风险最低、收益最明显的部分。确保错误信息友好，能指导用户修正参数。
谨慎设计“写操作”工具
：涉及交易广播的工具，设计上要增加“确认”环节。例如，工具可以返回一个完整的交易预览（包括金额、接收方、预估 Gas），并要求用户明确回复“确认发送”后，才真正执行广播。这能有效防止误操作。
拥抱“混合智能”
：不要指望 AI 能处理所有逻辑。把 AI 当作一个强大的自然语言解析器和流程编排器。复杂的业务逻辑（如价格滑点计算、最优路径选择）应该放在 MCP 服务器的工具实现里，用你熟悉的、可靠的代码来完成。AI 负责理解意图并触发这些可靠的“原子能力”。
社区协作
：关注 MCP 协议和 CryptoAPIs 生态的更新。这个共享项目很可能只是一个起点。你可以将自己开发的好用工具贡献回去，或者借鉴他人实现的工具。这种可组合性，正是开源和协议化带来的最大红利。
最后，这个项目目前可能还处于早期阶段，文档和工具覆盖度可能不全。遇到问题，除了查看项目 Issue 和源码，最直接的方式是结合 CryptoAPIs 的官方 API 文档和 MCP 协议规范，自己动手去实现缺失的部分。这个过程本身，就是对区块链和 AI 两大前沿领域如何结合的一次深度实践。
