Starknet MCP Server

Starknet MCP 服务

一个功能全面的 Starknet 区块链模型上下文协议（MCP）服务。该服务使 AI Agent 能够与 Starknet 网络交互、查询区块链数据、管理钱包并与智能合约交互。

📋 目录

• 概述
• 功能
• 支持的网络
• 先决条件
• 安装
• 服务配置
• 用法
• API 参考
  • 工具
  • 资源
  • 提示词
• 与 AI 助手搭配使用
• 安全注意事项
• 项目结构
• 开发规范
• 文档
• 许可证

🔭 概述

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

主要功能包括：

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

所有服务都通过统一的 MCP 工具和资源接口提供，方便 AI Agent 发现和使用 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：Ethereum Sepolia 上的 Starknet 测试网

🛠️ 前置条件

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

📦 安装

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 starknet-mcp-server：

npx -y @smithery/cli install @mcpdotdirect/starknet-mcp-server --client claude

选项 1：无需安装即可使用（npx）

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

# Run the stdio server without installation
npx @mcpdotdirect/starknet-mcp-server

# Run the HTTP server without installation
npx @mcpdotdirect/starknet-mcp-server http

这会自动下载并运行最新版本，无需提前安装。

选项 2：全局安装

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

# Install globally
npm install -g @mcpdotdirect/starknet-mcp-server

# Then run from anywhere
starknet-mcp-server
starknet-mcp-server http

选项 3：安装到本地项目

# Add to your project
npm install @mcpdotdirect/starknet-mcp-server

# Using yarn
yarn add @mcpdotdirect/starknet-mcp-server

# Using pnpm
pnpm add @mcpdotdirect/starknet-mcp-server

然后添加到 package.json 脚本中：

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

选项 4：从源代码运行

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

# Clone the repository
git clone https://github.com/mcpdotdirect/starknet-mcp-server.git
cd starknet-mcp-server

# Install dependencies
npm install

# Start the stdio server
npm start

# Or start the HTTP server
npm run start:http

如需在开发时自动重新加载：

# Development mode with stdio
npm run dev

# Development mode with HTTP
npm run dev:http

⚙️ 服务配置

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

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

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

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

🔍 使用方法

运行服务

你可以通过两种模式运行 Starknet MCP Server：

# Run the server in stdio mode (for CLI tools and AI assistants)
npx @mcpdotdirect/starknet-mcp-server

# Run the server in HTTP mode (for web applications)
npx @mcpdotdirect/starknet-mcp-server http

HTTP 服务默认在端口 3000 上运行，并提供 REST API 和用于实时通信的服务器发送事件（SSE）。

从 Cursor 连接

要从 Cursor 连接到 Starknet MCP 服务：

1. 打开 Cursor，进入 Settings（左下角的齿轮图标）

2. 点击左侧边栏中的“Features”

3. 向下滚动到“MCP Servers”部分

4. 点击“Add new MCP server”

5. 输入以下详细信息：

   • 服务名称：starknet-mcp-server
   • 类型：command
   • 命令：npx @mcpdotdirect/starknet-mcp-server

6. 点击“Save”

连接后，你可以直接在 Cursor 中使用 MCP 服务的功能。该服务会显示在 MCP Servers 列表中，你可以根据需要启用或禁用它。

在 Cursor 中使用 mcp.json

如需使用更便于移植的配置，以便与团队共享或在多个项目中使用，可以在项目根目录中创建 .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 服务：

# Add the MCP server using npx
claude mcp add starknet-mcp-server npx @mcpdotdirect/starknet-mcp-server

# Start Claude with the MCP server enabled
claude

示例：在 Cursor 中使用 MCP 服务

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

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

// starknet-example.js
async function main() {
  try {
    // When using with Cursor, you can simply ask Cursor to:
    // "Check the ETH balance of address 0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7 on Starknet mainnet"
    // Or "Lookup the Starknet ID for address 0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7"
    
    // Cursor will use the MCP server to execute these operations 
    // without requiring any additional code from you
  } catch (error) {
    console.error("Error:", error.message);
  }
}

main();

2. 在 Cursor 中打开该文件后，你可以要求 Cursor：
   • “查询 vitalik.stark 的 ETH 余额”
   • “获取 Starknet 上最新区块的信息”
   • “查询 NFT #123 在合约 0x... 中的所有者”

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

// Example of using the MCP client to check an ETH balance using Starknet ID
const mcp = new McpClient("http://localhost:3000");

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

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

示例：解析 Starknet ID

// Example of using the MCP client to resolve a Starknet ID to an address
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
// }

示例：调用智能合约

// Example of using the MCP client to call a smart contract function
const mcp = new McpClient("http://localhost:3000");

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

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

在 Node.js 项目中使用

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

// Start the MCP server as a child process
const { spawn } = require('child_process');
const mcpServer = spawn('npx', ['@mcpdotdirect/starknet-mcp-server']);

// Connect to it with the MCP client
const mcp = new McpClient({ process: mcpServer });

// Now you can use the client
const networks = await mcp.invokeTool("get_supported_starknet_networks", {
  random_string: "any"
});
console.log("Supported networks:", 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 提示词

对于大模型交互，此服务提供以下提示词：

• 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 助手配合使用时：

1. 将 AI 助手配置为使用此 MCP 服务
2. 然后，助手即可使用工具与 Starknet 交互
3. 示例查询：
   • “地址 0x04d07e40e93398ed3c76981e449d3446f7c4e52aac5b3e8a37d7b0ca30845a5d 的 ETH 余额是多少？”
   • “查询地址 0x04d07e40e93398ed3c76981e449d3446f7c4e52aac5b3e8a37d7b0ca30845a5d 对应的 Starknet ID”
   • “Starknet 主网上的最新区块包含什么内容？”
   • “获取有关交易 0x7e3a33ab42f2e24184763563b7b8482b53e3b89831ebc3eacf29d4d11f5198 的信息”
   • “将 Starknet ID vitalik.stark 解析为一个地址”

🔒 安全注意事项

• 私钥仅用于签署交易，服务不会存储私钥
• 所有代币金额均以便于阅读的格式指定（例如 ETH、STRK、代币单位），而非以 wei 或最小单位指定
• 执行操作前，务必验证并清理输入参数
• 考虑在生产环境中实施额外的身份验证机制
• 在生产环境中为 HTTP 服务使用 HTTPS
• 实施速率限制以防止滥用
• 对于高价值服务，可考虑添加确认步骤

📁 项目结构

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

🛠️ 开发约定

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

1. 在所有资源、工具和提示词名称中使用下划线（_），而不是连字符（-）

   // Good: Uses underscores
   server.tool(
     "starknet_contract_call",
     "Description of the tool",
     {
       contract_address: z.string().describe("The contract address")
     },
     async (params) => {
       // Tool implementation
     }
   );
   

2. 此命名约定可确保与 Cursor 和其他 AI 工具兼容

📚 文档

如需了解更多信息，请参阅：

• Model Context Protocol
• Starknet.js 文档
• Starknet 文档
• StarknetID 文档

📄 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。