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

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:

Open Cursor and go to Settings (gear icon in the bottom left)
Click on "Features" in the left sidebar
Scroll down to "MCP Servers" section
Click "Add new MCP server"
Enter the following details:
- Server name: starknet-mcp-server
- Type: command
- Command: npx @mcpdotdirect/starknet-mcp-server
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:

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

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

get_starknet_chain_info: Get information about a Starknet network
get_supported_starknet_networks: Get a list of supported Starknet networks

Balance Tools

get_starknet_eth_balance: Get the ETH balance for a Starknet address or Starknet ID
get_starknet_token_balance: Get the balance of any token for an address
get_starknet_strk_balance: Get the STRK token balance for an address
get_starknet_native_balances: Get all native token balances (ETH and STRK) for an address

StarknetID Tools

resolve_starknet_name: Get the Starknet ID for an address
resolve_starknet_address: Get the address for a Starknet ID
get_starknet_profile: Get the full Starknet ID profile for an address
validate_starknet_domain: Check if a string is a valid Starknet ID

Block Tools

get_starknet_block: Get information about a specific block
get_starknet_block_transactions: Get transactions in a specific block

Transaction Tools

get_starknet_transaction: Get details about a transaction
get_starknet_transaction_receipt: Get transaction receipt
check_starknet_transaction_status: Check if a transaction is confirmed

Contract Tools

call_starknet_contract: Call a read-only function on a contract
get_starknet_contract_class: Get the class (ABI and other information) of a contract
execute_starknet_contract: Execute a contract call (write operation)

Token Tools

get_starknet_token_info: Get information about a token
get_starknet_token_supply: Get the total supply of a token
check_starknet_nft_ownership: Check if an address owns a specific NFT
get_starknet_nft_balance: Get the number of NFTs owned by an address

Transfer Tools

transfer_starknet_eth: Transfer ETH from one account to another (amounts in human-readable format)
transfer_starknet_strk: Transfer STRK from one account to another (amounts in human-readable format)
transfer_starknet_token: Transfer ERC20 tokens from one account to another (amounts in human-readable format)

Available MCP Resources

The server provides the following MCP resources:

Network Resources

starknet://{network}/chain: Get chain information for a specific network
starknet://networks: Get a list of all supported networks

Block Resources

starknet://{network}/block/{blockIdentifier}: Get information about a specific block
starknet://{network}/block/latest: Get the latest block

Address Resources

starknet://{network}/address/{address}: Get information about an address

Transaction Resources

starknet://{network}/tx/{txHash}: Get transaction information

StarknetID Resources

starknet://{network}/id/address/{address}: Resolve an address to a Starknet ID
starknet://{network}/id/name/{name}: Resolve a Starknet ID to an address
starknet://{network}/id/profile/{address}: Get the Starknet ID profile for an address

Available MCP Prompts

For LLM interactions, the server provides these prompts:

explore_starknet_block: Explore information about a specific Starknet block
explore_starknet_address: Get information about a Starknet address
explore_starknet_transaction: Get information about a Starknet transaction
lookup_starknet_id: Look up a Starknet ID or resolve an address to a Starknet ID
explore_starknet_id_profile: Explore a full Starknet ID profile

🔍 Usage with AI Assistants

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

Configure your AI assistant to use this MCP server
The assistant can then use tools to interact with Starknet
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

Private keys are used only for transaction signing and are never stored by the server
All token amounts are specified in human-readable format (e.g., ETH, STRK, token units) rather than in wei or smallest units
Always validate and sanitize input parameters before executing operations
Consider implementing additional authentication mechanisms for production use
Use HTTPS for the HTTP server in production environments
Implement rate limiting to prevent abuse
For high-value services, consider adding confirmation steps

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

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

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.

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
.github/workflows		.github/workflows
bin		bin
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
package.json		package.json
tsconfig.json		tsconfig.json

License

mcpdotdirect/starknet-mcp-server

Folders and files

Latest commit

History

Repository files navigation