Skip to content
Somnia MCP Site Documentation

Somnia MCP Server

The Somnia MCP Server is a Model Context Protocol (MCP) implementation that provides tools for interacting with the Somnia blockchain, which is based on Ethereum Virtual Machine (EVM) technology. This server allows AI assistants and other MCP-compatible clients to query blockchain data, manage transactions, and interact with smart contracts on the Somnia network.

The MCP server exposes a comprehensive set of tools that enable:

  • Retrieving network information and gas prices
  • Querying account balances and transaction history
  • Interacting with ERC20 tokens and NFTs
  • Reading smart contract data and executing state-changing operations
  • Transferring native tokens and ERC20 tokens
  • Resolving ENS names and reverse lookups
  • Deploying new smart contracts to the blockchain
  • Analyzing transaction volumes and holder distributions
  • Verifying and getting contract source code
  • Batch operations and multicall functionality

Architecture

Section titled “Architecture”
graph TD
    A[MCP Client] --> B[MCP Server]
    B --> C[Tools Layer]
    C --> D[Services Layer]
    D --> E[EVM Blockchain]
    E --> F[Somnia Network]


    C --> G[Network Tools]
    C --> H[Balance Tools]
    C --> I[Transaction Tools]
    C --> J[Token Tools]
    C --> K[Contract Tools]
    C --> L[Analytics Tools]


    G --> G1[get_chain_info]
    G --> G2[get_gas_price]
    G --> G3[get_fee_data]


    H --> H1[get_balance]
    H --> H2[get_erc20_balance]


    I --> I1[get_transaction]
    I --> I2[transfer_native_token]
    I --> I3[estimate_gas]


    J --> J1[get_token_info]
    J --> J2[get_nft_info]
    J --> J3[get_ens_name]


    K --> K1[read_contract]
    K --> K2[write_contract]
    K --> K3[deploy_contract]
    K --> K4[multicall_contract]


    L --> L1[get_transaction_volume]
    L --> L2[get_top_holders]

The architecture consists of three main layers:

  1. Tools Layer: MCP tool definitions organized into 6 categories (Network, Balance, Transaction, Token, Contract, Analytics)
  2. Services Layer: Business logic for blockchain interactions using Viem library with advanced features like multicall, batch operations, and contract verification
  3. Blockchain Layer: Direct connection to the Somnia EVM network with support for all network operations

Supported Networks

Section titled “Supported Networks”

The server supports all Somnia networks, with defaults to the testnet. You can specify different networks using the network parameter in most tools.

Getting Started

Section titled “Getting Started”

To use the Somnia MCP Server:

  1. Set up your MCP client to connect to this server
  2. Configure your private key in environment variables for transaction tools
  3. Start querying the blockchain!

Tool Categories

Section titled “Tool Categories”

Error Handling

Section titled “Error Handling”

All tools include comprehensive error handling. If an operation fails, the tool will return an error message with details about what went wrong. Common errors include:

  • Network connection issues
  • Invalid addresses or parameters
  • Insufficient funds for transfers
  • Contract method not found
  • Block range limits exceeded (max 1000 blocks)
  • Contract verification failures
  • Multicall execution errors
  • Gas estimation failures
  • Private key not configured for write operations

Security Notes

Section titled “Security Notes”
  • Transaction tools require a private key set in the PRIVATE_KEY environment variable
  • Always verify addresses and amounts before executing transfers
  • Use testnet for development and testing