Thirdweb MCP server

The thirdweb MCP server provides a unified interface to access thirdweb's blockchain tools and services through the standardized Model Context Protocol. It enables integration with Nebula, Insight, Engine, EngineCloud, and Storage services for tasks like on-chain analysis, contract interactions, and decentralized storage.

Installation

Prerequisites

• Python 3.10 or higher
• uv

Install with uvx

THIRDWEB_SECRET_KEY=... \
    uvx thirdweb-mcp

Install with pipx

pipx install thirdweb-mcp

THIRDWEB_SECRET_KEY=... \
    thirdweb-mcp

Install from source

git clone https://github.com/thirdweb-dev/ai.git thirdweb-ai
cd thirdweb-ai/python/thirdweb-mcp
uv sync

Configuration

The server requires specific configuration based on which services you want to enable:

1. thirdweb Secret Key: Required for Nebula, Insight, Storage, and EngineCloud services. Obtain from the thirdweb dashboard.
2. Chain IDs: Blockchain network IDs to connect to (e.g., 1 for Ethereum mainnet, 137 for Polygon).
3. Engine Configuration: If using the Engine service, you'll need the Engine URL and authentication JWT.
4. EngineCloud Configuration: For EngineCloud operations, you may need the Vault Access Token for server wallet operations.

Usage

Command-line Options

# Basic usage with default settings (stdio transport with Nebula and Insight)
THIRDWEB_SECRET_KEY=... thirdweb-mcp 

# Using SSE transport on a custom port
THIRDWEB_SECRET_KEY=... thirdweb-mcp --transport sse --port 8080

# Enabling all services with specific chain IDs
THIRDWEB_SECRET_KEY=... thirdweb-mcp --chain-id 1 --chain-id 137 \
    --engine-url YOUR_ENGINE_URL \
    --engine-auth-jwt YOUR_ENGINE_JWT \ 
    --engine-backend-wallet-address YOUR_ENGINE_BACKEND_WALLET_ADDRESS \
    --vault-access-token YOUR_VAULT_ACCESS_TOKEN

Environment Variables

You can also configure the MCP server using environment variables:

• THIRDWEB_SECRET_KEY: Your thirdweb API secret key
• THIRDWEB_ENGINE_URL: URL endpoint for thirdweb Engine service
• THIRDWEB_ENGINE_AUTH_JWT: Authentication JWT token for Engine
• THIRDWEB_ENGINE_BACKEND_WALLET_ADDRESS: Wallet address for Engine backend
• THIRDWEB_VAULT_ACCESS_TOKEN: Vault access token for EngineCloud server wallet operations

Integration with Claude Desktop

To add this MCP server to Claude Desktop:

1. Install the MCP: pipx install thirdweb-mcp

2. Create or edit the Claude Desktop configuration file at:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

3. Add the following configuration:

   {
     "mcpServers": {
       "thirdweb-mcp": {
         "command": "thirdweb-mcp",
         "args": [], 
         "env": {
           "THIRDWEB_SECRET_KEY": "your thirdweb secret key from dashboard",
           "THIRDWEB_ENGINE_URL": "(OPTIONAL) your engine url",
           "THIRDWEB_ENGINE_AUTH_JWT": "(OPTIONAL) your engine auth jwt",
           "THIRDWEB_ENGINE_BACKEND_WALLET_ADDRESS": "(OPTIONAL) your engine backend wallet address",
           "THIRDWEB_VAULT_ACCESS_TOKEN": "(OPTIONAL) your vault access token for EngineCloud"
         },
       }
     }
   }
   

4. Restart Claude Desktop for the changes to take effect.

Available Services

Nebula

• Analyze smart contract code
• Contract interactions and deployments
• Autonomous onchain tasks execution

Insight

• Query on-chain data across multiple networks
• Analyze transactions, blocks, and smart contract events
• Monitor wallet activities and token movements

Engine

• Deploy smart contracts
• Interact with deployed contracts
• Manage wallet connections and transactions

EngineCloud

• Create and manage server wallets with KMS integration
• Read from and write to smart contracts
• Send transactions and query transaction history
• Check native token balances on various chains

Storage

• Upload files, directories, and JSON data to IPFS
• Retrieve content from IPFS using thirdweb gateway
• Preserve directory structures when uploading

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "thirdweb-mcp" '{"command":"thirdweb-mcp","args":[],"env":{"THIRDWEB_SECRET_KEY":"your thirdweb secret key from dashboard","THIRDWEB_ENGINE_URL":"(OPTIONAL) your engine url","THIRDWEB_ENGINE_AUTH_JWT":"(OPTIONAL) your engine auth jwt","THIRDWEB_ENGINE_BACKEND_WALLET_ADDRESS":"(OPTIONAL) your engine backend wallet address","THIRDWEB_VAULT_ACCESS_TOKEN":"(OPTIONAL) your vault access token for EngineCloud"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "thirdweb-mcp": {
            "command": "thirdweb-mcp",
            "args": [],
            "env": {
                "THIRDWEB_SECRET_KEY": "your thirdweb secret key from dashboard",
                "THIRDWEB_ENGINE_URL": "(OPTIONAL) your engine url",
                "THIRDWEB_ENGINE_AUTH_JWT": "(OPTIONAL) your engine auth jwt",
                "THIRDWEB_ENGINE_BACKEND_WALLET_ADDRESS": "(OPTIONAL) your engine backend wallet address",
                "THIRDWEB_VAULT_ACCESS_TOKEN": "(OPTIONAL) your vault access token for EngineCloud"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "thirdweb-mcp": {
            "command": "thirdweb-mcp",
            "args": [],
            "env": {
                "THIRDWEB_SECRET_KEY": "your thirdweb secret key from dashboard",
                "THIRDWEB_ENGINE_URL": "(OPTIONAL) your engine url",
                "THIRDWEB_ENGINE_AUTH_JWT": "(OPTIONAL) your engine auth jwt",
                "THIRDWEB_ENGINE_BACKEND_WALLET_ADDRESS": "(OPTIONAL) your engine backend wallet address",
                "THIRDWEB_VAULT_ACCESS_TOKEN": "(OPTIONAL) your vault access token for EngineCloud"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect