> ## Documentation Index
> Fetch the complete documentation index at: https://seilabs-docs-bridge-release-v6-6-3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Enable AI assistants to interact with Sei networks through natural language using the Model Context Protocol

The Sei Model Context Protocol (MCP) Server enables AI assistants to interact with Sei networks through natural language. Built on the [Model Context Protocol](https://modelcontextprotocol.io/) standard, it provides blockchain tools for AI coding assistants.

<Info>The Sei MCP Server is open source. Contribute at [github.com/sei-protocol/sei-js](https://github.com/sei-protocol/sei-js/tree/main/packages/mcp-server). `@sei-js/mcp-server@1` requires Node.js 20 or newer.</Info>

The server starts in read-only mode. Wallet tools that sign or broadcast are hidden unless you set `WALLET_MODE=private-key` and `PRIVATE_KEY` on the default stdio transport.

## What is MCP?

The Model Context Protocol is an open standard that connects AI systems with external tools and data sources. It enables:

* Real-time data access from external services
* Function execution and operations
* Context preservation across interactions
* Specialized capabilities beyond base training

The Sei MCP Server leverages this protocol to bring blockchain functionality directly to your AI assistant.

## Capabilities

| Category           | Features                                                                            |
| ------------------ | ----------------------------------------------------------------------------------- |
| Account Management | Wallet addresses • Balance queries • Contract verification                          |
| Token Operations   | SEI, ERC-20, ERC-721, and ERC-1155 reads. Transfers and approvals need wallet mode. |
| Blockchain Data    | Block information • Transaction details • Network status                            |
| Smart Contracts    | State queries. Function execution and contract deploys need wallet mode.            |
| Networks           | Mainnet • Testnet                                                                   |

## Setup guide

<Tabs>
  <Tab title="Cursor">
    ### Cursor Setup

    <Steps>
      <Step title="Open Settings">
        Navigate to `Cursor → Settings → Cursor Settings → MCP`
      </Step>

      <Step title="Configure Server">
        Click **"Add new Global MCP server"** and add this configuration to `mcp.json`:

        ```json theme={null}
        {
          "mcpServers": {
            "sei-mcp-server": {
              "command": "npx",
              "args": ["-y", "@sei-js/mcp-server"]
            }
          }
        }
        ```
      </Step>

      <Step title="Restart">
        Restart Cursor to activate the MCP server. You'll see a notification when it's ready.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Windsurf">
    ### Windsurf Setup

    <Steps>
      <Step title="Open Settings">
        Navigate to `Windsurf → Settings → Windsurf Settings → Cascade`
      </Step>

      <Step title="Add Configuration">
        Add the Sei MCP Server to your configuration:

        ```json theme={null}
        {
          "mcpServers": {
            "sei": {
              "command": "npx",
              "args": ["-y", "@sei-js/mcp-server"]
            }
          }
        }
        ```
      </Step>

      <Step title="Activate">
        Save and restart Windsurf. The server loads automatically.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Desktop">
    ### Claude Desktop Setup

    <Steps>
      <Step title="Install Claude">
        Download [Claude Desktop](https://claude.ai/download) from Anthropic.
      </Step>

      <Step title="Edit Configuration">
        Open **Settings** → **Developer** → **Edit Config** and add:

        ```json theme={null}
        {
          "mcpServers": {
            "sei": {
              "command": "npx",
              "args": ["-y", "@sei-js/mcp-server"]
            }
          }
        }
        ```
      </Step>

      <Step title="Restart">
        Save and restart Claude Desktop to enable Sei tools.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude CLI">
    ### Claude CLI Setup

    <Steps>
      <Step title="Install CLI">
        ```bash theme={null}
        npm install -g @anthropic-ai/claude-code
        ```
      </Step>

      <Step title="Add Server">
        ```bash theme={null}
        claude mcp add sei-mcp-server npx @sei-js/mcp-server
        ```
      </Step>

      <Step title="Start Session">
        ```bash theme={null}
        claude
        ```

        The Sei MCP Server activates automatically in your session.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Private key setup

The server starts in read-only mode. To enable wallet tools over the default stdio transport, add both variables to the server's `env` configuration:

```json theme={null}
{
  "mcpServers": {
    "sei": {
      "command": "npx",
      "args": ["-y", "@sei-js/mcp-server"],
      "env": {
        "WALLET_MODE": "private-key",
        "PRIVATE_KEY": "0x_your_private_key_here"
      }
    }
  }
}
```

<Warning>Create a dedicated wallet for MCP operations. Never use your main wallet's private key. The `0x` prefix on `PRIVATE_KEY` is optional. Wallet mode is blocked on HTTP transports. Startup fails if private-key mode is misconfigured instead of silently disabling wallet tools.</Warning>

Export your private key from your wallet:

* Look for **Export Private Key** or **Show Private Key** in wallet settings
* Fund the wallet with small amounts for testing

## Features

The Sei MCP Server enables your AI assistant to:

* Query account balances, tokens, NFTs, blocks, and transactions (read-only)
* Search the official Sei docs, including `@sei-js` references (`search_docs`)
* Monitor network status for Pacific-1 and Atlantic-2
* Execute token transfers, NFT transfers, contract writes, and deploys when wallet mode is enabled on stdio

## Available tools

Read-only tools stay registered when wallet mode is disabled. Signing and broadcasting tools are hidden until you enable wallet mode on stdio.

Network arguments accept `sei`, `sei-testnet`, `1329`, `1328`, `0x531`, or `0x530`. Unknown networks are rejected. Chain-info responses omit RPC URLs.

`search_docs` queries [docs.sei.io](/). There is no `search_sei_js_docs` tool.

### Core operations

| Tool                           | Purpose                                 | Example                                 | Wallet mode |
| ------------------------------ | --------------------------------------- | --------------------------------------- | ----------- |
| `search_docs`                  | Search the official Sei docs            | "How do I use the staking precompile?"  | No          |
| `get_supported_networks`       | List supported networks                 | "Which Sei networks are available?"     | No          |
| `get_chain_info`               | Network chain ID and latest block       | "Show Sei mainnet info"                 | No          |
| `get_balance`                  | Native SEI balance                      | "Check balance of 0x123..."             | No          |
| `is_contract`                  | Verify a contract address               | "Is 0x789... a contract?"               | No          |
| `read_contract`                | Call a read-only contract function      | "Read DEX reserves"                     | No          |
| `estimate_gas`                 | Estimate gas for a call                 | "How much gas does this transfer need?" | No          |
| `get_address_from_private_key` | Address for the configured key          | "What's my wallet address?"             | Required    |
| `transfer_sei`                 | Send SEI                                | "Send 1 SEI to 0x456..."                | Required    |
| `write_contract`               | Call a state-changing contract function | "Call transfer on this contract"        | Required    |
| `deploy_contract`              | Deploy bytecode                         | "Deploy this contract"                  | Required    |

### Token management

| Tool                     | Purpose                                                 | Example                     | Wallet mode |
| ------------------------ | ------------------------------------------------------- | --------------------------- | ----------- |
| `get_token_info`         | ERC-20 metadata                                         | "Get USDC token info"       | No          |
| `get_token_balance`      | ERC-20 balance (`tokenAddress`, `ownerAddress`)         | "Check my USDC balance"     | No          |
| `transfer_token`         | ERC-20 transfer (`tokenAddress`, `toAddress`, `amount`) | "Send 100 USDC to 0x123..." | Required    |
| `approve_token_spending` | ERC-20 approval                                         | "Approve a DEX for USDC"    | Required    |

Reach for `get_token_balance` and `transfer_token`. The server also registers aliases for backward compatibility: `get_erc20_balance` and `get_token_balance_erc20` behave like `get_token_balance` but name the holder argument `address` instead of `ownerAddress`, and `transfer_erc20` is `transfer_token` under a different name with the same arguments.

### NFT and ERC-1155

| Tool                    | Purpose                                                                                            | Example                          | Wallet mode |
| ----------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------- | ----------- |
| `get_nft_info`          | ERC-721 metadata                                                                                   | "Show NFT #123 details"          | No          |
| `check_nft_ownership`   | ERC-721 owner check (`ownerAddress` in, boolean out). Failures error instead of returning `false`. | "Does 0x… own NFT #456?"         | No          |
| `get_nft_balance`       | ERC-721 collection balance                                                                         | "How many NFTs do I own?"        | No          |
| `get_erc1155_balance`   | ERC-1155 balance                                                                                   | "Check my ERC-1155 balance"      | No          |
| `get_erc1155_token_uri` | ERC-1155 token URI                                                                                 | "Get the URI for this ERC-1155"  | No          |
| `transfer_nft`          | ERC-721 `safeTransferFrom`                                                                         | "Send NFT #789 to 0xABC..."      | Required    |
| `transfer_erc1155`      | ERC-1155 transfer                                                                                  | "Send this ERC-1155 to 0xABC..." | Required    |

NFT ownership lookup failures propagate as errors instead of reporting `false`. ERC-721 transfers use `safeTransferFrom`, so contract recipients must implement `onERC721Received`.

### Blocks and transactions

| Tool                      | Purpose             | Example                         | Wallet mode |
| ------------------------- | ------------------- | ------------------------------- | ----------- |
| `get_block_by_number`     | Block by number     | "Get block 12345"               | No          |
| `get_latest_block`        | Latest block        | "Get the latest block"          | No          |
| `get_transaction`         | Transaction data    | "Show tx 0xTXID..."             | No          |
| `get_transaction_receipt` | Transaction receipt | "Get the receipt for 0xTXID..." | No          |

## AI prompts

These prompts are always available, including in read-only mode:

<CardGroup cols={2}>
  <Card title="explore_block" icon="cube">
    Analyze block data
  </Card>

  <Card title="analyze_transaction" icon="receipt">
    Break down transaction details
  </Card>

  <Card title="analyze_address" icon="magnifying-glass">
    Inspect an address and its activity
  </Card>

  <Card title="analyze_token" icon="coins">
    Summarize token metadata and balances
  </Card>

  <Card title="interact_with_contract" icon="file-code">
    Walk through calling a contract
  </Card>

  <Card title="explain_evm_concept" icon="book-open">
    Explain an EVM concept in context
  </Card>

  <Card title="compare_networks" icon="code-compare">
    Compare Pacific-1 and Atlantic-2
  </Card>
</CardGroup>

These prompts require wallet mode on the stdio transport:

<CardGroup cols={3}>
  <Card title="my_wallet_address" icon="wallet">
    Return the configured wallet address
  </Card>

  <Card title="send_transaction_guidance" icon="paper-plane">
    Guide you through sending a transaction
  </Card>

  <Card title="token_transfer_guidance" icon="arrow-right-arrow-left">
    Guide you through a token transfer
  </Card>
</CardGroup>

## Usage examples

<CardGroup cols={1}>
  <Card title="Query balance" icon="scale-balanced">
    "What's my SEI balance?"

    Calls `get_balance` and returns the wallet balance and address.
  </Card>

  <Card title="Send transaction" icon="paper-plane">
    "Send 1 SEI to 0x742d35Cc6634C0532925a3b844Bc454e4438f44e"

    Calls `transfer_sei` and returns the transaction hash. Requires wallet mode.
  </Card>

  <Card title="Contract analysis" icon="file-code">
    "Is 0x3894085ef7ff0f0aedf52e2a2704928d1ec074f1 a contract?"

    Calls `is_contract` and identifies the contract type and metadata.
  </Card>
</CardGroup>

## Resource URIs

Access blockchain data through standardized URIs:

```bash theme={null}
# Network data
evm://sei/chain
evm://sei-testnet/chain

# Block information
evm://sei/block/latest
evm://sei/block/12345

# Transactions
evm://sei/tx/0xabc123...

# Token data
evm://sei/token/0x3894085ef7ff0f0aedf52e2a2704928d1ec074f1
evm://sei/token/0x389.../balanceOf/0x742d...

# NFT data
evm://sei/nft/0xNFT_ADDRESS/123
evm://sei/nft/0xNFT_ADDRESS/123/isOwnedBy/0x742d...
```

## Configuration

Client-launched servers (`npx` from Cursor, Claude Desktop, or similar) read variables from the MCP client's `env` object. A project-local `.env` is loaded only when the process starts in a directory that contains one, such as a local checkout.

```bash theme={null}
# Default: read-only mode
WALLET_MODE=disabled

# Optional RPC overrides
MAINNET_RPC_URL=https://your-mainnet-rpc.example
TESTNET_RPC_URL=https://your-testnet-rpc.example

# Optional wallet tools for stdio transport only
# WALLET_MODE=private-key
# PRIVATE_KEY=0x_your_private_key_here
```

| Variable                       | Default            | Notes                                                         |
| ------------------------------ | ------------------ | ------------------------------------------------------------- |
| `WALLET_MODE`                  | `disabled`         | `private-key` enables signing tools on stdio                  |
| `PRIVATE_KEY`                  | unset              | Required when `WALLET_MODE=private-key`. `0x` prefix optional |
| `MAINNET_RPC_URL`              | public mainnet RPC | Used only for upstream connections                            |
| `TESTNET_RPC_URL`              | public testnet RPC | Used only for upstream connections                            |
| `SERVER_TRANSPORT`             | `stdio`            | `streamable-http` or `http-sse` for HTTP                      |
| `SERVER_HOST`                  | `localhost`        | HTTP listener host                                            |
| `SERVER_PORT`                  | `8080`             | HTTP listener port                                            |
| `SERVER_PATH`                  | `/mcp`             | HTTP endpoint path                                            |
| `SSE_MAX_SESSIONS`             | `100`              | Legacy SSE concurrent session cap                             |
| `STREAMABLE_HTTP_MAX_REQUESTS` | `100`              | Streamable HTTP concurrent request cap                        |

CLI flags such as `--http` are not supported. Set `SERVER_TRANSPORT` instead. Run `npx -y @sei-js/mcp-server --help` for the current reference.

### HTTP server mode

Streamable HTTP is the HTTP transport for new integrations:

```bash theme={null}
SERVER_TRANSPORT=streamable-http \
SERVER_HOST=127.0.0.1 \
SERVER_PORT=8080 \
npx -y @sei-js/mcp-server
```

Connect to `http://127.0.0.1:8080/mcp`. Change the listener with `SERVER_HOST`, `SERVER_PORT`, and `SERVER_PATH`.

Legacy HTTP/SSE is available for older clients:

```bash theme={null}
SERVER_TRANSPORT=http-sse \
SERVER_HOST=127.0.0.1 \
npx -y @sei-js/mcp-server
```

For `http-sse`, GET `{SERVER_PATH}` is the event stream. Clients POST messages to `{SERVER_PATH}/message?sessionId=<id>`.

<Warning>
  HTTP transports reject wallet mode. They do not authenticate callers or validate `Origin`/`Host`. Bind to `127.0.0.1` for local use, and put any public exposure behind an authenticating reverse proxy.
</Warning>

## Security guidelines

<Warning>
  Use a dedicated wallet with only the funds you need for testing. Set `PRIVATE_KEY` through environment variables or the MCP client's `env` object. Never commit it. Review transaction history on that wallet regularly.
</Warning>

Beyond a throwaway test wallet, treat the signing key as production infrastructure: cap the value any single transaction can move, hold funds in a multi-signature wallet and let the agent operate a low-balance hot wallet, restrict the agent to an allowlist of contract addresses, and rate-limit the tools that sign or broadcast.

## Troubleshooting

**Connection issues**: Verify Node.js 20 or later is installed and restart your AI assistant.

**Private key errors**: Set `WALLET_MODE=private-key`, provide a valid 32-byte secp256k1 key (`0x` prefix optional), and use the default stdio transport.

**Cursor: The model returned an error. Try disabling the MCP servers, or switch models**: Disable "Auto" in the model
menu and select a specific model e.g. `claude-4-sonnet`