MCP 服务器

Starknet MCP Server

提供 LLM 工具，使其能够与 Starknet 交互的 MCP 服务器。

mcpdotdirect

研究与数据

访问服务器

README

Starknet MCP 服务器

一个用于 Starknet 区块链的综合模型上下文协议 (MCP) 服务器。该服务器为 AI 代理提供与 Starknet 网络交互、查询区块链数据、管理钱包以及与智能合约交互的能力。

📋 目录

概述
特性
支持的网络
前提条件
安装
服务器配置
用法
API 参考
- 工具
- 资源
- 提示
与 AI 助手一起使用
安全注意事项
项目结构
开发约定
文档
许可证

🔭 概述

Starknet MCP 服务器利用模型上下文协议为 AI 代理提供区块链服务。它为 Starknet 生态系统提供了一个全面的接口，使 AI 助手能够通过自然语言与 Starknet 区块链数据和操作进行交互。

主要功能包括：

读取区块链状态（余额、交易、区块）
与 Cairo 智能合约交互
转移代币（ETH、STRK 和其他 ERC20 代币）
使用 NFT 和代币元数据
解析 StarknetID 域名（类似于 Ethereum 的 ENS）
使用适当的交易处理进行读写操作

所有服务都通过 MCP 工具和资源的一致接口公开，使 AI 代理可以轻松发现和使用 Starknet 区块链功能。每个接受 Starknet 地址的工具也支持 StarknetID，在后台自动将人类可读的身份解析为地址。

✨ 特性

Starknet 集成：使用 Starknet.js 的完整 Starknet 区块链集成
网络支持：支持 Mainnet 和 Sepolia 测试网
StarknetID 集成：Starknet ID 与地址之间的相互解析
原生代币支持：支持 ETH 和 STRK 原生代币
智能合约交互：调用和查询 Starknet 智能合约
双重传输：作为 stdio 服务器或 HTTP 服务器运行，以满足不同的集成需求
AI 就绪：设计用于 Claude、GPT 和其他 AI 助手

区块链信息

查询链信息（链 ID、最新区块）
探索区块详细信息和交易
查看交易收据和状态
获取地址信息和合约数据

原生代币操作

获取任何地址的 ETH 和 STRK 余额
在帐户之间转移 ETH 和 STRK
查看组合的原生代币余额

代币操作

获取 ERC20 代币余额和信息
转移 ERC20 代币
查看代币供应和元数据
检查代币所有权

NFT 操作

按代币 ID 检查 NFT 所有权
获取 NFT 集合信息
查看地址的 NFT 余额

智能合约交互

调用只读合约函数
执行合约写入并确认交易
获取合约存储信息
查看 ABI 和合约类信息

StarknetID

将 Starknet 地址解析为 Starknet ID
将 Starknet ID 解析为地址
获取包含验证数据的完整 Starknet ID 配置文件
验证 Starknet 域名

🔧 支持的网络

服务器支持以下 Starknet 网络：

Mainnet：主要的 Starknet 生产网络
Sepolia：Starknet 在 Ethereum Sepolia 上的测试网

🛠️ 前提条件

Bun 1.0.0 或更高版本（推荐）
Node.js 18.0.0 或更高版本

📦 安装

选项 1：无需安装即可使用 (npx)

最简单的入门方法是使用 npx 直接运行该软件包：

# 运行 stdio 服务器，无需安装
npx @mcpdotdirect/starknet-mcp-server

# 运行 HTTP 服务器，无需安装
npx @mcpdotdirect/starknet-mcp-server http

这将自动下载并运行最新版本，而无需先安装它。

选项 2：全局安装

如果您计划经常使用它，您可以全局安装它：

# 全局安装
npm install -g @mcpdotdirect/starknet-mcp-server

# 然后从任何地方运行
starknet-mcp-server
starknet-mcp-server http

选项 3：本地项目安装

# 添加到您的项目
npm install @mcpdotdirect/starknet-mcp-server

# 使用 yarn
yarn add @mcpdotdirect/starknet-mcp-server

# 使用 pnpm
pnpm add @mcpdotdirect/starknet-mcp-server

然后添加到您的 package.json 脚本：

"scripts": {
  "starknet-mcp": "starknet-mcp-server",
  "starknet-mcp-http": "starknet-mcp-server http"
}

选项 4：从源代码运行

如果您想从源代码运行或在本地开发：

# 克隆存储库
git clone https://github.com/mcpdotdirect/starknet-mcp-server.git
cd starknet-mcp-server

# 安装依赖项
npm install

# 启动 stdio 服务器
npm start

# 或者启动 HTTP 服务器
npm run start:http

对于具有自动重新加载功能的开发：

# 具有 stdio 的开发模式
npm run dev

# 具有 HTTP 的开发模式
npm run dev:http

⚙️ 服务器配置

服务器使用以下默认配置：

默认网络：Mainnet
服务器端口：3000（HTTP 模式）
服务器主机：0.0.0.0（可从任何网络接口访问）

这些值已硬编码在应用程序中。如果您需要修改它们，您可以编辑以下文件：

对于网络配置：src/core/chains.ts
对于服务器配置：src/server/http-server.ts

🔍 用法

运行服务器

您可以在两种模式下运行 Starknet MCP 服务器：

# 在 stdio 模式下运行服务器（用于 CLI 工具和 AI 助手）
npx @mcpdotdirect/starknet-mcp-server

# 在 HTTP 模式下运行服务器（用于 Web 应用程序）
npx @mcpdotdirect/starknet-mcp-server http

HTTP 服务器默认在端口 3000 上运行，并提供 REST API 和服务器发送事件 (SSE) 以进行实时通信。

从 Cursor 连接

要从 Cursor 连接到 Starknet MCP 服务器：

打开 Cursor 并转到设置（左下角的齿轮图标）
单击左侧边栏中的“Features”
向下滚动到“MCP Servers”部分
单击“Add new MCP server”
输入以下详细信息：
- Server name: starknet-mcp-server
- Type: command
- Command: npx @mcpdotdirect/starknet-mcp-server
单击“Save”

连接后，您可以直接在 Cursor 中使用 MCP 服务器的功能。该服务器将显示在 MCP 服务器列表中，并且可以根据需要启用/禁用。

将 mcp.json 与 Cursor 一起使用

对于您可以与您的团队共享或跨项目使用的更便携的配置，您可以在项目的根目录中创建一个 .cursor/mcp.json 文件：

{
  "mcpServers": {
    "starknet-mcp-server": {
      "command": "npx",
      "args": [
        "@mcpdotdirect/starknet-mcp-server"
      ]
    },
    "starknet-mcp-http": {
      "command": "npx",
      "args": [
        "@mcpdotdirect/starknet-mcp-server",
        "http"
      ]
    }
  }
}

将此文件放在项目的 .cursor 目录中（如果不存在则创建它），并且 Cursor 将在您在该项目中工作时自动检测并使用这些 MCP 服务器配置。

具有 SSE 的 HTTP 模式

如果您正在开发 Web 应用程序并希望使用服务器发送事件 (SSE) 连接到 HTTP 服务器，您可以使用此配置：

{
  "mcpServers": {
    "starknet-mcp-sse": {
      "url": "http://localhost:3000/sse"
    }
  }
}

使用 Claude CLI 连接

如果您正在使用 Claude CLI，您只需两个命令即可连接到 MCP 服务器：

# 使用 npx 添加 MCP 服务器
claude mcp add starknet-mcp-server npx @mcpdotdirect/starknet-mcp-server

# 启动 Claude 并启用 MCP 服务器
claude

示例：在 Cursor 中使用 MCP 服务器

配置 MCP 服务器后，您可以轻松地在 Cursor 中使用它。例如：

在您的项目中创建一个新的 JavaScript/TypeScript 文件：

// starknet-example.js
async function main() {
  try {
    // 当与 Cursor 一起使用时，您可以简单地要求 Cursor：
    // "检查 Starknet mainnet 上地址 0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7 的 ETH 余额"
    // 或者 "查找地址 0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7 的 Starknet ID"
    
    // Cursor 将使用 MCP 服务器执行这些操作
    // 而无需您提供任何其他代码
  } catch (error) {
    console.error("Error:", error.message);
  }
}

main();

在 Cursor 中打开该文件后，您可以要求 Cursor：
- "检查 vitalik.stark 的 ETH 余额"
- "获取有关 Starknet 上最新区块的信息"
- "查找集合 0x... 中 NFT #123 的所有者"

示例：使用 Starknet ID 获取 ETH 余额

// 使用 MCP 客户端检查使用 Starknet ID 的 ETH 余额的示例
const mcp = new McpClient("http://localhost:3000");

const result = await mcp.invokeTool("get_starknet_eth_balance", {
  address: "vitalik.stark", // Starknet ID 代替地址
  network: "mainnet"
});

console.log(result);
// {
//   wei: "1000000000000000000",
//   ether: "1.0"
// }

示例：解析 Starknet ID

// 使用 MCP 客户端将 Starknet ID 解析为地址的示例
const mcp = new McpClient("http://localhost:3000");

const result = await mcp.invokeTool("resolve_starknet_address", {
  name: "vitalik.stark",
  network: "mainnet"
});

console.log(result);
// {
//   starknetId: "vitalik.stark",
//   address: "0x04d07e40e93398ed3c76981e449d3446f7c4e52aac5b3e8a37d7b0ca30845a5d",
//   resolved: true
// }

示例：调用智能合约

// 使用 MCP 客户端调用智能合约函数的示例
const mcp = new McpClient("http://localhost:3000");

const result = await mcp.invokeTool("call_starknet_contract", {
  contractAddress: "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7", // ETH 合约
  entrypoint: "totalSupply",
  calldata: [],
  network: "mainnet"
});

console.log(result);
// {
//   result: ["0x84b6c7d5970d5a73abe"]
// }

在 Node.js 项目中使用

如果您想以编程方式在您的 Node.js 项目中使用 MCP 服务器：

// 将 MCP 服务器作为子进程启动
const { spawn } = require('child_process');
const mcpServer = spawn('npx', ['@mcpdotdirect/starknet-mcp-server']);

// 使用 MCP 客户端连接到它
const mcp = new McpClient({ process: mcpServer });

// 现在您可以使用客户端
const networks = await mcp.invokeTool("get_supported_starknet_networks", {
  random_string: "any"
});
console.log("支持的网络:", networks);

对于更高级的用法，您可以围绕 HTTP API 创建一个包装类，或者使用 Axios 等库进行更简洁的 API 调用。

📚 API 参考

可用的 MCP 工具

此服务器实现以下 MCP 工具：

网络工具

get_starknet_chain_info：获取有关 Starknet 网络的信息
get_supported_starknet_networks：获取支持的 Starknet 网络列表

余额工具

get_starknet_eth_balance：获取 Starknet 地址或 Starknet ID 的 ETH 余额
get_starknet_token_balance：获取地址的任何代币的余额
get_starknet_strk_balance：获取地址的 STRK 代币余额
get_starknet_native_balances：获取地址的所有原生代币余额（ETH 和 STRK）

StarknetID 工具

resolve_starknet_name：获取地址的 Starknet ID
resolve_starknet_address：获取 Starknet ID 的地址
get_starknet_profile：获取地址的完整 Starknet ID 配置文件
validate_starknet_domain：检查字符串是否为有效的 Starknet ID

区块工具

get_starknet_block：获取有关特定区块的信息
get_starknet_block_transactions：获取特定区块中的交易

交易工具

get_starknet_transaction：获取有关交易的详细信息
get_starknet_transaction_receipt：获取交易收据
check_starknet_transaction_status：检查交易是否已确认

合约工具

call_starknet_contract：调用合约上的只读函数
get_starknet_contract_class：获取合约的类（ABI 和其他信息）
execute_starknet_contract：执行合约调用（写入操作）

代币工具

get_starknet_token_info：获取有关代币的信息
get_starknet_token_supply：获取代币的总供应量
check_starknet_nft_ownership：检查地址是否拥有特定的 NFT
get_starknet_nft_balance：获取地址拥有的 NFT 数量

转移工具

transfer_starknet_eth：将 ETH 从一个帐户转移到另一个帐户（金额采用人类可读的格式）
transfer_starknet_strk：将 STRK 从一个帐户转移到另一个帐户（金额采用人类可读的格式）
transfer_starknet_token：将 ERC20 代币从一个帐户转移到另一个帐户（金额采用人类可读的格式）

可用的 MCP 资源

服务器提供以下 MCP 资源：

网络资源

starknet://{network}/chain：获取特定网络的链信息
starknet://networks：获取所有支持的网络列表

区块资源

starknet://{network}/block/{blockIdentifier}：获取有关特定区块的信息
starknet://{network}/block/latest：获取最新区块

地址资源

starknet://{network}/address/{address}：获取有关地址的信息

交易资源

starknet://{network}/tx/{txHash}：获取交易信息

StarknetID 资源

starknet://{network}/id/address/{address}：将地址解析为 Starknet ID
starknet://{network}/id/name/{name}：将 Starknet ID 解析为地址
starknet://{network}/id/profile/{address}：获取地址的 Starknet ID 配置文件

可用的 MCP 提示

对于 LLM 交互，服务器提供以下提示：

explore_starknet_block：探索有关特定 Starknet 区块的信息
explore_starknet_address：获取有关 Starknet 地址的信息
explore_starknet_transaction：获取有关 Starknet 交易的信息
lookup_starknet_id：查找 Starknet ID 或将地址解析为 Starknet ID
explore_starknet_id_profile：探索完整的 Starknet ID 配置文件

🔍 与 AI 助手一起使用

将此服务器与 Claude 或 GPT 等 AI 助手一起使用时：

配置您的 AI 助手以使用此 MCP 服务器
然后，助手可以使用工具与 Starknet 交互
示例查询：
- "地址 0x04d07e40e93398ed3c76981e449d3446f7c4e52aac5b3e8a37d7b0ca30845a5d 的 ETH 余额是多少？"
- "查找地址 0x04d07e40e93398ed3c76981e449d3446f7c4e52aac5b3e8a37d7b0ca30845a5d 的 Starknet ID"
- "Starknet mainnet 上的最新区块是什么？"
- "获取有关交易 0x7e3a33ab42f2e24184763563b7b8482b53e3b89831ebc3eacf29d4d11f5198 的信息"
- "将 Starknet ID vitalik.stark 解析为地址"

🔒 安全注意事项

私钥仅用于交易签名，服务器永远不会存储
所有代币金额均以人类可读的格式指定（例如，ETH、STRK、代币单位），而不是以 wei 或最小单位指定
在执行操作之前，始终验证和清理输入参数
考虑为生产用途实施其他身份验证机制
在生产环境中使用 HTTPS 作为 HTTP 服务器
实施速率限制以防止滥用
对于高价值服务，请考虑添加确认步骤

📁 项目结构

starknet-mcp-server/
├── src/
│   ├── index.ts                # Main stdio server entry point
│   ├── server/                 # Server-related files
│   │   ├── http-server.ts      # HTTP server with SSE
│   │   └── server.ts           # General server setup
│   ├── core/
│   │   ├── chains.ts           # Chain definitions and utilities
│   │   ├── resources.ts        # MCP resources implementation
│   │   ├── tools.ts            # MCP tools implementation
│   │   ├── prompts.ts          # MCP prompts implementation
│   │   └── services/           # Core blockchain services
│   │       ├── index.ts        # Service exports
│   │       ├── balance.ts      # Balance services
│   │       ├── blocks.ts       # Block services
│   │       ├── clients.ts      # Client utilities
│   │       ├── contracts.ts    # Contract interactions
│   │       ├── starknetid.ts   # Starknet ID services
│   │       ├── tokens.ts       # Token services
│   │       ├── transactions.ts # Transaction services
│   │       ├── transfer.ts     # Transfer services
│   │       └── utils.ts        # Utility functions
├── package.json
├── tsconfig.json
└── README.md

🛠️ 开发约定

添加自定义工具、资源或提示时：

在所有资源、工具和提示名称中使用下划线 (_) 而不是连字符 (-)

// 良好：使用下划线
server.tool(
  "starknet_contract_call",
  "工具的描述",
  {
    contract_address: z.string().describe("合约地址")
  },
  async (params) => {
    // 工具实现
  }
);

此命名约定确保与 Cursor 和其他 AI 工具的兼容性

📚 文档

有关更多信息：

📄 许可证

本项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。