GitHub - mcpdotdirect/starknet-mcp-server: MCP server that provides LLM with tools for interacting with Starknet (original) (raw)

Starknet MCP Server

smithery badge License: MIT TypeScript MCP Starknet.js

A comprehensive Model Context Protocol (MCP) server for the Starknet blockchain. This server provides AI agents with the ability to interact with Starknet networks, query blockchain data, manage wallets, and interact with smart contracts.

Starknet Server MCP server

📋 Contents

🔭 Overview

The Starknet MCP Server leverages the Model Context Protocol to provide blockchain services to AI agents. It offers a comprehensive interface to the Starknet ecosystem, powering AI assistants with the ability to interact with Starknet blockchain data and operations through natural language.

Key capabilities include:

All services are exposed through a consistent interface of MCP tools and resources, making it easy for AI agents to discover and use Starknet blockchain functionality. Every tool that accepts Starknet addresses also supports StarknetID, automatically resolving human-readable identities to addresses behind the scenes.

✨ Features

Blockchain Information

Native Token Operations

Token Operations

NFT Operations

Smart Contract Interaction

StarknetID

🔧 Networks Supported

The server supports the following Starknet networks:

🛠️ Prerequisites

📦 Installation

Installing via Smithery

To install starknet-mcp-server for Claude Desktop automatically via Smithery:

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

Option 1: Use without installation (npx)

The easiest way to get started is to use npx to run the package directly:

Run the stdio server without installation

npx @mcpdotdirect/starknet-mcp-server

Run the HTTP server without installation

npx @mcpdotdirect/starknet-mcp-server http

This will automatically download and run the latest version without needing to install it first.

Option 2: Global installation

If you plan to use it frequently, you can install it globally:

Install globally

npm install -g @mcpdotdirect/starknet-mcp-server

Then run from anywhere

starknet-mcp-server starknet-mcp-server http

Option 3: Local project installation

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

Then add to your package.json scripts:

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

Option 4: Running from source

If you want to run from source or develop locally:

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

For development with auto-reload:

Development mode with stdio

npm run dev

Development mode with HTTP

npm run dev:http

⚙️ Server Configuration

The server uses the following default configuration:

These values are hardcoded in the application. If you need to modify them, you can edit the following files:

🔍 Usage

Running the Server

You can run the Starknet MCP Server in two modes:

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

The HTTP server runs on port 3000 by default and provides both a REST API and Server-Sent Events (SSE) for real-time communication.

Connecting from Cursor

To connect to the Starknet MCP server from Cursor:

  1. Open Cursor and go to Settings (gear icon in the bottom left)
  2. Click on "Features" in the left sidebar
  3. Scroll down to "MCP Servers" section
  4. Click "Add new MCP server"
  5. Enter the following details:
    • Server name: starknet-mcp-server
    • Type: command
    • Command: npx @mcpdotdirect/starknet-mcp-server
  6. Click "Save"

Once connected, you can use the MCP server's capabilities directly within Cursor. The server will appear in the MCP Servers list and can be enabled/disabled as needed.

Using mcp.json with Cursor

For a more portable configuration that you can share with your team or use across projects, you can create an .cursor/mcp.json file in your project's root directory:

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

Place this file in your project's .cursor directory (create it if it doesn't exist), and Cursor will automatically detect and use these MCP server configurations when working in that project.

HTTP Mode with SSE

If you're developing a web application and want to connect to the HTTP server with Server-Sent Events (SSE), you can use this configuration:

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

Connecting using Claude CLI

If you're using Claude CLI, you can connect to the MCP server with just two commands:

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

Example: Using the MCP Server in Cursor

After configuring the MCP server, you can easily use it in Cursor. For example:

  1. Create a new JavaScript/TypeScript file in your project:

// 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();

  1. With the file open in Cursor, you can ask Cursor to:
    • "Check the ETH balance of vitalik.stark"
    • "Get information about the latest block on Starknet"
    • "Look up the owner of NFT #123 in collection 0x..."

Example: Getting an ETH Balance with Starknet ID

// 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" // }

Example: Resolving a 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: Calling a Smart Contract

// 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"] // }

Using in a Node.js Project

If you want to programmatically use the MCP server in your Node.js project:

// 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);

For more advanced usage, you can create a wrapper class around the HTTP API or use libraries like Axios for cleaner API calls.

📚 API Reference

Available MCP Tools

This server implements the following MCP tools:

Network Tools

Balance Tools

StarknetID Tools

Block Tools

Transaction Tools

Contract Tools

Token Tools

Transfer Tools

Available MCP Resources

The server provides the following MCP resources:

Network Resources

Block Resources

Address Resources

Transaction Resources

StarknetID Resources

Available MCP Prompts

For LLM interactions, the server provides these prompts:

🔍 Usage with AI Assistants

When using this server with AI assistants like Claude or GPT:

  1. Configure your AI assistant to use this MCP server
  2. The assistant can then use tools to interact with Starknet
  3. Example queries:
    • "What's the ETH balance of address 0x04d07e40e93398ed3c76981e449d3446f7c4e52aac5b3e8a37d7b0ca30845a5d?"
    • "Look up the Starknet ID for address 0x04d07e40e93398ed3c76981e449d3446f7c4e52aac5b3e8a37d7b0ca30845a5d"
    • "What's in the latest block on Starknet mainnet?"
    • "Get information about transaction 0x7e3a33ab42f2e24184763563b7b8482b53e3b89831ebc3eacf29d4d11f5198"
    • "Resolve the Starknet ID vitalik.stark to an address"

🔒 Security Considerations

📁 Project Structure

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

🛠️ Development Conventions

When adding custom tools, resources, or prompts:

  1. Use underscores (_) instead of hyphens (-) in all resource, tool, and prompt names
    // 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. This naming convention ensures compatibility with Cursor and other AI tools

📚 Documentation

For more information about:

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.