内容
# kaspa-simple-mcp
Kaspa 区块链的只读 [模型上下文协议（MCP）](https://modelcontextprotocol.io) 服务器。通过简单、确定的工具，让 AI 代理查询 Kaspa 数据 — 无需节点。
为与 MCP 兼容的客户端（如 [OpenCode](https://opencode.ai)、Claude、Cursor 等）一起使用而构建。
## 功能
- **余额和未花费交易输出（UTXOs）** — 单个、批量和历史余额；单个和批量 UTXO 查询
- **交易** — 按 ID 查找、搜索、接受检查、批量计算、计数和历史
- **地址** — 交易、UTXOs、计数、分页历史、活动检查、名称解析、分布、顶级地址
- **区块** — 单个区块、区块范围、按蓝分值排序的区块、虚拟链
- **网络信息** — DAG 信息、算力（当前 + 历史 + 样本）、货币供应、价格、区块奖励、减半、Kaspad 信息、虚拟链蓝分值、健康状况、市值、流通和总供应、最大算力
- **费用估算** — 当前网络优先级费用率
所有数据均来自公共 Kaspa REST API。无需 API 密钥。只读。
本项目是托管在 [api.kaspa.org](https://api.kaspa.org) 上的 Kaspa 公共 API 的薄封装。所有底层区块链数据和基础设施的功劳归于 Kaspa 团队和社区。
## 安装
```bash
npm install -g kaspa-simple-mcp
```
或使用 npx 直接运行：
```bash
npx kaspa-simple-mcp
```
## 网络配置
默认情况下，服务器查询 **主网**。设置 `KASPA_NETWORK` 环境变量以切换：
| 值 | API URL |
|---|---|
| `mainnet`（默认） | `https://api.kaspa.org` |
| `testnet-10` | `https://api-tn10.kaspa.org` |
### 客户端配置示例
**OpenCode（`opencode.json`）：**
```json
{
"mcp": {
"kaspa-simple-mcp": {
"command": "npx",
"args": ["-y", "kaspa-simple-mcp"],
"env": {
"KASPA_NETWORK": "testnet-10"
}
}
}
}
```
**Claude Desktop（`claude_desktop_config.json`）：**
```json
{
"mcpServers": {
"kaspa": {
"command": "npx",
"args": ["-y", "kaspa-simple-mcp"],
"env": {
"KASPA_NETWORK": "testnet-10"
}
}
}
}
```
省略 `env` 块以使用主网。
## 工具参考
### 余额
| 工具 | 参数 | 描述 |
|------|--------|-------------|
| `get_balance` | `address` | 地址的已确认 KAS 余额 |
| `get_balances_batch` | `addresses`（数组，1-100） | 最多 100 个地址的余额 |
| `get_address_balance_history` | `address`，`dayOrMonth` | 每日或每月的余额历史 |
### 未花费交易输出（UTXOs）
| 工具 | 参数 | 描述 |
|------|--------|-------------|
| `get_address_utxos` | `address` | 地址的 UTXOs |
| `get_address_utxo_count` | `address` | 地址的 UTXO 计数 |
| `get_utxos_batch` | `addresses`（数组，1-100） | 最多 100 个地址的 UTXOs |
### 交易
| 工具 | 参数 | 描述 |
|------|--------|-------------|
| `get_transaction` | `txId` | 交易状态、时间戳、总价值和顶级输出 |
| `get_address_transactions` | `address`，`limit?`，`offset?` | 地址的近期交易 |
| `get_address_transaction_count` | `address` | 地址的总交易计数 |
| `get_address_transactions_page` | `address`，`limit?`，`before?`，`after?` | 游标分页交易历史 |
| `search_transactions` | `transactionIds?`，`acceptingBlueScoreGte?`，`acceptingBlueScoreLt?`，`resolvePreviousOutpoints?`，`acceptance?` | 按 ID、蓝分值或接受度搜索交易 |
| `get_transactions_acceptance` | `transactionIds`（数组，1-200） | 检查交易是否被接受 |
| `calculate_transaction_mass` | `version`，`inputs`，`outputs`，`lockTime?`，`subnetworkId?` | 计算交易质量 |
| `get_transaction_count` | 无 | 当前总交易计数 |
| `get_transaction_count_history` | `dayOrMonth` | 每日或每月的交易计数历史 |
### 地址信息
| 工具 | 参数 | 描述 |
|------|--------|-------------|
| `get_address_name` | `address` | 解析地址名称 |
| `get_address_names` | 无 | 列出所有已知的地址名称 |
| `get_addresses_active` | `addresses`（数组，1-100） | 检查地址是否活跃 |
| `get_top_addresses` | 无 | 按余额排名的顶级地址 |
| `get_address_distribution` | 无 | 地址余额分布 |
### 活跃地址
| 工具 | 参数 | 描述 |
|------|--------|-------------|
| `get_active_addresses_count` | 无 | 当前活跃地址计数 |
| `get_active_addresses_count_history` | `dayOrMonth` | 每日或每月的活跃地址历史 |
### 区块
| 工具 | 参数 | 描述 |
|------|--------|-------------|
| `get_block` | `blockId`，`includeTransactions?`，`includeColor?` | 按哈希获取区块详细信息 |
| `get_blocks` | `lowHash`，`includeBlocks?`，`includeTransactions?` | 从起始哈希获取区块哈希 |
| `get_blocks_from_bluescore` | `blueScore?`，`blueScoreGte?`，`blueScoreLt?`，`includeTransactions?` | 按蓝分值获取区块 |
| `get_virtual_chain` | `blueScoreGte`，`limit?`，`resolveInputs?`，`includeCoinbase?` | 从蓝分值获取虚拟链区块 |
### 网络信息
| 工具 | 参数 | 描述 |
|------|--------|-------------|
| `get_blockdag_info` | 无 | DAG 统计信息（提示、难度等） |
| `get_hashrate` | 无 | 当前网络算力 |
| `get_hashrate_history` | `dayOrMonth` | 每日或每月的算力历史 |
| `get_hashrate_history_samples` | `limit?` | 近期的算力样本 |
| `get_coin_supply` | 无 | 货币供应详情 |
| `get_circulating_supply` | 无 | 流通供应 |
| `get_total_supply` | 无 | 总供应 |
| `get_max_hashrate` | 无 | 历史最大算力 |
| `get_price` | 无 | 当前 KAS 价格 |
| `get_marketcap` | 无 | 当前市值 |
| `get_block_reward` | 无 | 当前区块奖励 |
| `get_halving_info` | 无 | 减半计划 |
| `get_kaspad_info` | 无 | Kaspad 节点信息 |
| `get_virtual_chain_blue_score` | 无 | 当前虚拟链蓝分值 |
| `get_health` | 无 | API 健康检查 |
| `get_fee_estimate` | 无 | 当前优先级费用率 |
## 输出特性
- 所有货币价值均以 **KAS**（而非 sompi）返回，为带有 8 位小数的字符串
- 响应为确定的 JSON — 易于 LLMs 解析
- 错误包含描述性消息
- 无需身份验证
## 开发
```bash
npm run build
# 在主网上测试（默认）
node test_integration.mjs
# 在 testnet-10 上测试
$env:KASPA_NETWORK="testnet-10"; node test_integration.mjs
```
## 许可证
MIT
