内容
# 🔗 ABI MCP 服务器
[](https://www.npmjs.com/package/@iqai/mcp-abi)
[](https://opensource.org/licenses/ISC)
## 📖 概述
ABI MCP 服务器使 AI 代理能够使用 ABI（应用程序二进制接口）与任何以太坊兼容的智能合约进行交互。该服务器根据合约 ABI 动态生成 MCP 工具，允许与任何智能合约无缝交互，无需自定义工具实现。
通过实施模型上下文协议（MCP），该服务器允许大型语言模型（LLM）直接通过其上下文窗口读取合约状态、执行交易并与去中心化应用程序交互。
## ✨ 功能
* **动态工具生成**：在运行时从任何合约 ABI 自动创建 MCP 工具。
* **读取函数**：查询合约状态（视图/纯函数）而无需发送交易。
* **写入函数**：执行状态更改的交易，支持钱包签名。
* **多链支持**：通过可配置的 RPC 端点与任何 EVM 兼容的区块链配合使用。
* **类型安全交互**：根据 ABI 规范验证函数参数。
## 📦 安装
### 🚀 使用 npx（推荐）
要使用此服务器而无需全局安装：
```bash
npx @iqai/mcp-abi
```
### 🔧 从源代码构建
```bash
git clone https://github.com/IQAIcom/mcp-abi.git
cd mcp-abi
pnpm install
pnpm run build
```
## ⚡ 与 MCP 客户端一起运行
将以下配置添加到您的 MCP 客户端设置中（例如，`claude_desktop_config.json`）。
### 📋 最小配置
```json
{
"mcpServers": {
"smart-contract-abi": {
"command": "npx",
"args": ["-y", "@iqai/mcp-abi"],
"env": {
"CONTRACT_ABI": "[{\"inputs\":[{\"name\":\"account\",\"type\":\"address\"}],\"name\":\"balanceOf\",\"outputs\":[{\"type\":\"uint256\"}],\"stateMutability\":\"view\",\"type\":\"function\"}]",
"CONTRACT_ADDRESS": "0xaB195B090Cc60C1EFd4d1cEE94Bf441F5931C01b",
"CONTRACT_NAME": "ERC20"
}
}
}
}
```
### ⚙️ 高级配置（本地构建）
```json
{
"mcpServers": {
"smart-contract-abi": {
"command": "node",
"args": ["/absolute/path/to/mcp-abi/dist/index.js"],
"env": {
"WALLET_PRIVATE_KEY": "your_wallet_private_key_here",
"CONTRACT_ABI": "[{\"inputs\":[{\"name\":\"to\",\"type\":\"address\"},{\"name\":\"amount\",\"type\":\"uint256\"}],\"name\":\"transfer\",\"outputs\":[{\"type\":\"bool\"}],\"stateMutability\":\"nonpayable\",\"type\":\"function\"}]",
"CONTRACT_ADDRESS": "0xaB195B090Cc60C1EFd4d1cEE94Bf441F5931C01b",
"CONTRACT_NAME": "ERC20",
"CHAIN_ID": "252",
"RPC_URL": "https://rpc.frax.com"
}
}
}
}
```
## 🔐 配置（环境变量）
| 变量 | 必需 | 描述 | 默认值 |
| :--- | :--- | :--- | :--- |
| `CONTRACT_ABI` | 是 | 合约 ABI 的 JSON 字符串表示 | - |
| `CONTRACT_ADDRESS` | 是 | 区块链上部署的合约地址 | - |
| `CONTRACT_NAME` | 否 | 合约的友好名称（用作工具名称前缀） | `CONTRACT` |
| `WALLET_PRIVATE_KEY` | 用于写入 | 签名交易的私钥（写入函数必填） | - |
| `CHAIN_ID` | 否 | 区块链网络链 ID | `252`（Fraxtal） |
| `RPC_URL` | 否 | 自定义 RPC 端点 URL | 链的默认值 |
## 💡 使用示例
### 🔍 读取合约状态
* "检查钱包 0xabc... 的代币余额..."
* "代币的总供应量是多少？"
* "获取所有者 0x456... 对spender 0x123... 的许可额度"
### 📝 执行交易
* "向地址 0xabc... 转移 100 代币..."
* "批准spender 0x123... 花费 1000 代币"
* "向钱包 0xdef... 铸造一个新的 NFT"
### 📊 合约分析
* "此合约有哪些可用的函数？"
* "显示我可以调用的所有读取函数"
* "转移函数需要哪些参数？"
## 🛠️ MCP 工具
工具根据提供的合约 ABI 动态生成。ABI 中的每个函数都成为一个 MCP 工具：
* **读取函数（视图/纯函数）**：以合约名称为前缀的工具（例如，`erc20_balanceOf`、`erc20_totalSupply`）
* **写入函数**：用于状态更改操作的工具（例如，`erc20_transfer`、`erc20_approve`）
ERC20 合约的示例工具名称，`CONTRACT_NAME=ERC20`：
* `erc20_balanceOf` - 查询代币余额
* `erc20_transfer` - 转移代币
* `erc20_approve` - 批准花费
* `erc20_allowance` - 检查许可额度
<!-- AUTO-GENERATED TOOLS START -->
> **注意：** 工具根据加载的合约 ABI 动态生成。
> 工具名称遵循 `{contractname}_{functionname}` 模式。
### 动态工具生成
当您加载合约 ABI 时，会自动为 ABI 中的每个函数创建工具：
- **读取函数** 变成查询工具（无需 Gas）
- **写入函数** 变成执行工具（需要钱包）
### 通用参数
所有生成的工具都接受相同的参数模式：
| 参数 | 类型 | 必需 | 默认值 | 描述 |
|-----------|------|----------|---------|-------------|
| `args` | 数组 | 否 | `[]` | 函数参数数组。例如：`["0x123...", 100, true]` |
### 示例生成的工具
如果您加载名为“USDC”的 ERC-20 代币合约，将生成以下工具：
- `usdc_name` - 查询代币名称
- `usdc_symbol` - 查询代币符号
- `usdc_decimals` - 查询代币小数位
- `usdc_totalSupply` - 查询代币总供应量
- `usdc_balanceOf` - 查询地址余额
- `usdc_transfer` - 向地址转移代币
- `usdc_approve` - 批准花费许可额度
- `usdc_transferFrom` - 代表另一个地址转移代币
### 工具响应格式
**读取函数：**
```
✅ 成功查询 {functionName}
📊 结果：
{JSON 结果}
```
**写入函数：**
```
✅ 成功执行 {functionName}
🔗 交易哈希：{hash}
📦 区块编号：{blockNumber}
⛽ Gas 使用量：{gasUsed}
✅ 状态：成功
```
<!-- AUTO-GENERATED TOOLS END -->
## 👨💻 开发
### 🏗️ 构建项目
```bash
pnpm run build
```
### 👁️ 开发模式（监听）
```bash
pnpm run watch
```
### ✅ 校验和格式化
```bash
pnpm run lint
pnpm run format
```
### 📁 项目结构
* `src/tools/`：工具生成逻辑
* `src/services/`：合约交互服务
* `src/lib/`：共享实用程序
* `src/index.ts`：服务器入口点
## 📚 资源
* [模型上下文协议（MCP）](https://modelcontextprotocol.io)
* [以太坊 ABI 规范](https://docs.soliditylang.org/en/latest/abi-spec.html)
* [Viem 文档](https://viem.sh)
## ⚠️ 免责声明
此工具与区块链智能合约交互，可以执行实际交易。请安全存储私钥，永远不要将其提交到版本控制中。始终在主网部署之前在测试网中测试交互。与智能合约交易和交互存在风险。
## 📄 许可证
[ISC](LICENSE)
