MCP Server Setup

The Starknet MCP Server enables AI assistants to interact with Starknet through the Model Context Protocol (MCP). Once configured, your AI can check balances, execute swaps, transfer tokens, and call smart contracts.

What is MCP?

Model Context Protocol (MCP) is an open standard developed by Anthropic that allows AI assistants to connect to external data sources and tools. Instead of the AI generating code that you run manually, MCP lets the AI execute operations directly.

Traditional Approach:

You: "Transfer 10 USDC to 0x123..."
AI: "Here's the code to do that: ..."
You: *copy, paste, run code manually*

With MCP:

You: "Transfer 10 USDC to 0x123..."
AI: *executes starknet_transfer tool*
AI: "Done! Transaction hash: 0xabc..."

Why Starknet + MCP?

Starknet's native account abstraction makes it ideal for AI agent operations:

Architecture

+-------------------------------------------------------------+
|                      AI Assistant                           |
|            (Claude, Cursor, ChatGPT, etc.)                  |
+-----------------------------+-------------------------------+
                              | MCP Protocol (stdio)
                              v
+-------------------------------------------------------------+
|                   Starknet MCP Server                       |
|                                                             |
|   +-------------+  +-------------+  +-------------+         |
|   |   Balance   |  |  Transfer   |  |    Swap     |         |
|   |    Tools    |  |    Tool     |  |    Tools    |         |
|   +------+------+  +------+------+  +------+------+         |
|          |                |                |                |
|   +------+----------------+----------------+------+         |
|   |            Token Service (caching)            |         |
|   +------------------------+----------------------+         |
+----------------------------|--------------------------------+
                             |
            +----------------+----------------+
            |                |                |
            v                v                v
      +----------+     +----------+     +----------+
      | Starknet |     |   avnu   |     | Balance  |
      |   RPC    |     |   API    |     | Checker  |
      +----------+     +----------+     +----------+

Prerequisites

Before configuring any AI client, you need:

1. Node.js 18+ - Download
2. A Starknet Account - With private key access
3. RPC Endpoint - From Alchemy, Infura, or Blast
4. The MCP Server Built - See installation below

Installation

git clone https://github.com/keep-starknet-strange/starknet-agentic.git
cd starknet-agentic

pnpm install

pnpm build

# Get the absolute path
echo "$(pwd)/packages/starknet-mcp-server/dist/index.js"

Configuration

Choose your AI assistant below:

Claude Desktop

Create or edit the config file:

{
  "mcpServers": {
    "starknet": {
      "command": "node",
      "args": ["/absolute/path/to/starknet-agentic/packages/starknet-mcp-server/dist/index.js"],
      "env": {
        "STARKNET_RPC_URL": "https://starknet-sepolia.g.alchemy.com/v2/YOUR_API_KEY",
        "STARKNET_ACCOUNT_ADDRESS": "0x0123456789abcdef...",
        "STARKNET_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Restart Claude Desktop after saving the config. You should see "starknet" appear in the MCP servers list.

Claude Code (CLI)

Claude Code reads MCP configuration from .mcp.json in your project or home directory.

Create .mcp.json:

{
  "mcpServers": {
    "starknet": {
      "command": "node",
      "args": ["/absolute/path/to/starknet-agentic/packages/starknet-mcp-server/dist/index.js"],
      "env": {
        "STARKNET_RPC_URL": "https://starknet-sepolia.g.alchemy.com/v2/YOUR_API_KEY",
        "STARKNET_ACCOUNT_ADDRESS": "0x0123456789abcdef...",
        "STARKNET_PRIVATE_KEY": "0x..."
      }
    }
  }
}

The server connects automatically when Claude Code starts. Verify with:

claude /mcp

Cursor

Cursor supports MCP through its settings.

{
  "starknet": {
    "command": "node",
    "args": ["/absolute/path/to/starknet-agentic/packages/starknet-mcp-server/dist/index.js"],
    "env": {
      "STARKNET_RPC_URL": "https://starknet-sepolia.g.alchemy.com/v2/YOUR_API_KEY",
      "STARKNET_ACCOUNT_ADDRESS": "0x...",
      "STARKNET_PRIVATE_KEY": "0x..."
    }
  }
}

ChatGPT Desktop

ChatGPT desktop app now natively supports MCP. OpenAI adopted MCP in March 2025 and integrated it across their products.

VS Code with Continue

Continue is an open-source AI code assistant that supports MCP.

Edit ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "starknet",
      "command": "node",
      "args": ["/absolute/path/to/starknet-agentic/packages/starknet-mcp-server/dist/index.js"],
      "env": {
        "STARKNET_RPC_URL": "https://starknet-sepolia.g.alchemy.com/v2/YOUR_API_KEY",
        "STARKNET_ACCOUNT_ADDRESS": "0x...",
        "STARKNET_PRIVATE_KEY": "0x..."
      }
    }
  ]
}

Environment Variables

Network Configuration

Mainnet (default):

STARKNET_RPC_URL=https://starknet-mainnet.g.alchemy.com/v2/YOUR_KEY
AVNU_BASE_URL=https://starknet.api.avnu.fi
AVNU_PAYMASTER_URL=https://starknet.paymaster.avnu.fi

Sepolia Testnet:

STARKNET_RPC_URL=https://starknet-sepolia.g.alchemy.com/v2/YOUR_KEY
AVNU_BASE_URL=https://sepolia.api.avnu.fi
AVNU_PAYMASTER_URL=https://sepolia.paymaster.avnu.fi

Gasfree Transactions

The MCP server supports gasfree mode where transaction fees are paid in ERC-20 tokens instead of requiring ETH/STRK for gas.

User-Pays Mode (No API Key)

Without an API key, users pay gas in their chosen token:

"Transfer 10 USDC to 0x123... using gasfree mode"

The server will deduct a small amount of USDC (or specified gasToken) to cover fees.

Sponsored Mode (With API Key)

With AVNU_PAYMASTER_API_KEY, the dApp sponsor pays all gas fees:

"Swap 100 USDC to ETH with gasfree enabled"

The user pays nothing for gas—the API key holder covers the cost.

Verifying the Connection

After configuration, test the connection:

In Claude Desktop/Claude Code:

Check my ETH balance on Starknet

Expected response:

Using starknet_get_balance tool... Your ETH balance is 0.5 ETH (500000000000000000 wei)

In Cursor: Open the AI chat and ask:

What's my STRK balance?

Available Tools

The MCP server exposes 10 core tools plus 4 conditional tools:

For complete parameter documentation, see the MCP Tools Reference.

Example Interactions

Troubleshooting

Next Steps

• MCP Tools Reference - Complete tool documentation
• DeFi Operations - Swaps, liquidity, yield strategies
• Agent Identity - Register your agent on-chain with ERC-8004