Starknet MCP Server

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.

📋 Contents

• Overview
• Features
• Supported Networks
• Prerequisites
• Installation
• Server Configuration
• Usage
• API Reference
  • Tools
  • Resources
  • Prompts
• Usage with AI Assistants
• Security Considerations
• Project Structure
• Development Conventions
• Documentation
• License

🔭 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:

• Reading blockchain state (balances, transactions, blocks)
• Interacting with Cairo smart contracts
• Transferring tokens (ETH, STRK, and other ERC20 tokens)
• Working with NFTs and token metadata
• Resolving StarknetID domains (similar to ENS for Ethereum)
• Making both read and write operations with proper transaction handling

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

• Starknet Integration: Full Starknet blockchain integration using Starknet.js
• Network Support: Supports both Mainnet and Sepolia testnet
• StarknetID Integration: Resolution of Starknet IDs to addresses and vice versa
• Native Token Support: Support for both ETH and STRK native tokens
• Smart Contract Interaction: Call and query Starknet smart contracts
• Dual Transport: Run as stdio server or HTTP server for different integration needs
• AI-Ready: Designed to be used with Claude, GPT, and other AI assistants

Blockchain Information

• Query chain information (chain ID, latest block)
• Explore block details and transactions
• View transaction receipts and status
• Get address information and contract data

Native Token Operations

• Get ETH and STRK balances for any address
• Transfer ETH and STRK between accounts
• View combined native token balances

Token Operations

• Get ERC20 token balances and information
• Transfer ERC20 tokens
• View token supply and metadata
• Check token ownership

NFT Operations

• Check NFT ownership by token ID
• Get NFT collection information
• View NFT balances for addresses

Smart Contract Interaction

• Call read-only contract functions
• Execute contract writes with transaction confirmation
• Get contract storage information
• View ABIs and contract class information

StarknetID

• Resolve Starknet addresses to Starknet IDs
• Resolve Starknet IDs to addresses
• Get complete Starknet ID profiles with verification data
• Validate Starknet domains

🔧 Networks Supported

The server supports the following Starknet networks:

• Mainnet: The primary Starknet production network
• Sepolia: Starknet's testnet on Ethereum's Sepolia

🛠️ Prerequisites

• Bun 1.0.0 or higher (recommended)
• Node.js 18.0.0 or higher

📦 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:

• Default Network: Mainnet
• Server Port: 3000 (HTTP mode)
• Server Host: 0.0.0.0 (accessible from any network interface)

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

• For network configuration: src/core/chains.ts
• For server configuration: src/server/http-server.ts

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

2. 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