Skip to main content
Glama

Somnia MCP Server

This is the Somnia MCP server implementation. It provides various tools and resources for interacting with blockchain data.

Features

  • Get information about blockchain blocks

  • Retrieve token balances and transaction history

  • Access NFT metadata and ownership details

  • Fetch transaction details

  • Modular architecture for easy extension and customization

Related MCP server: Mina Archive Node

What can be Built on Top of Somnia MCP Server?

The Somnia MCP server provides a robust foundation for building various applications and services, including:

  • Decentralized finance (DeFi) applications

  • Non-fungible token (NFT) marketplaces

  • Blockchain explorers

  • Wallets and portfolio trackers

  • Custom analytics and reporting tools

  • Even AI assistants that can interact with blockchain data ( AI AGENTS )

Getting Started

To get started with the Somnia MCP server, follow these steps:

  1. Clone the repository:

    git clone https://github.com/vastavikadi/somnia-mcp.git
    cd somnia-mcp
  2. Install dependencies:

    npm install
  3. Configure environment variables: Create a .env file in the root directory and add your configuration:

    AUTH_TOKEN=your_auth_token

    NOTE: Replace your_auth_token with your actual AUTH_TOKEN(That is going to be the ORMI API KEY) from https://subgraph.somnia.network/ by creating an account.

  4. Build the server:

    npm run server:build
  5. After that make to add the mcp server to your MCP Client. In this case, my IDE (VSCode) is MCP Client. So I have to add the server in the mcp.json file present in the .vscode folder.

    {
      "servers": {
        "somniamcp": {
          "type": "stdio",
          "command": "node",
          "args": ["build/server.js"],
          "dev": {
            "watch": "src//*.ts",
            "debug": {
              "type": "node"
            }
          },
          "cwd": "${workspaceFolder}",
          "env": {
            "authToken": "${env:authToken}"
          }
        }
      },
      "inputs": []
    }
  6. You are now ready to start the Somnia MCP server!. Start from the mcp.json file.

  7. Restart the server from mcp.json file to get the fresh tools.

  8. Enjoy using the Somnia MCP server!. If you want to use in Copilot then simply use # and then the name of the tool you want to use. For example, #getBlockHeights to use the Get Block Heights tool.

NOTE: You can also run the command

npm run server:dev

to start the server in development mode with hot-reloading.

or

npm run server:inspect

to start the server in the inspect mode.

Contributing

Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.

Don't forget to give a star to the repository if you find it useful! ⭐

Available Tools

26 tools
getBlockHeightsA
Read-only

Get all block heights between two dates

Inputs: endDate (required), authToken (required), chainName (required), startDate (required).

getBlockTransactionsB
Read-only

Get transactions in a block

Inputs: authToken (required), chainName (required), blockNumber (required).

getBulkTransactionsA
Read-only

This API provides bulk transaction data for a wallet address in a 15-minute time bucket interval

Inputs: authToken (required), chainName (required), timeBucket (required), walletAddress (required).

getContractsWithHoldingsC
Read-only

Gets a list of contracts containing specific token with defined threshold.

Inputs: authToken (required), chainName (required), token_address (required).

getEarliestTransactionB
Read-only

Get the earliest transaction for an address

Inputs: authToken (required), chainName (required), walletAddress (required).

getERC1155BalanceB
Read-only

Returns a list of ERC-1155 token balances

Inputs: authToken (required), chainName (required), walletAddress (required).

getERC1155TransfersA
Read-onlyIdempotent

Get ERC1155 transfers for a specific wallet address

Inputs: authToken (required), chainName (required), walletAddress (required).

getERC20BalanceB
Read-only

Get ERC20 tokens balance of a wallet

Inputs: authToken (required), chainName (required), walletAddress (required).

getERC20TransfersA
Read-onlyIdempotent

Get ERC20 transfers for a specific wallet address

Inputs: authToken (required), chainName (required), walletAddress (required).

getERC721BalanceB
Read-only

Returns a list of ERC-721 token balances

Inputs: authToken (required), chainName (required), walletAddress (required).

getERC721TransfersA
Read-onlyIdempotent

Get ERC721 transfers for a specific wallet address

Inputs: authToken (required), chainName (required), walletAddress (required).

getHistoricalBalanceB
Read-onlyIdempotent

Commonly used to fetch the historical native, fungible (ERC20), and non-fungible (ERC721 & ERC1155) tokens held by an address at a given block height or date

Inputs: authToken (required), chainName (required), walletAddress (required).

getLatestTransactionsC
Read-only

Get latest transactions

Inputs: authToken (required), chainName (required).

getNFTtokensByAddressC
Read-only

Lists tokens for an NFT contract

Inputs: address (required), authToken (required), chainName (required).

getNFTtokensByIdForAddressA
Read-only

Gets token details for a specific token of an NFT contract.

Inputs: address (required), tokenId (required), authToken (required), chainName (required).

getOneBlockC
Read-only

Get a single block

Inputs: authToken (required), chainName (required), blockHeight (required).

getOneTransactionA
Read-only

Get a single transaction by its hash

Inputs: txHash (required), authToken (required), chainName (required).

getRecentTransactionsD
Read-only

Get recent transactions

Inputs: authToken (required), chainName (required), walletAddress (required).

getTokenBalanceC
Read-only

Get token balance for address for provided token address in query params

Inputs: authToken (required), chainName (required), walletAddress (required).

getTokenBalancePortfolioB
Read-onlyIdempotent

Commonly used to render a daily portfolio balance for an address broken down by the token. The timeframe is user-configurable, defaults to 30 days.

Inputs: authToken (required), chainName (required), walletAddress (required).

getTokenHoldersA
Read-only

Commonly used to get a list of all the token holders for a specified ERC20 or ERC721 token. Returns historic token holders when block-height is set (defaults to latest). Useful for building pie charts of token holders.

Inputs: authToken (required), chainName (required), tokenAddress (required).

getTopicTransactionLogsB
Read-only

Get logs for transactions matching the provided topic

Inputs: authToken (required), chainName (required), topicHash (required).

getTransactionLogsC
Read-only

Get logs from blocks

Inputs: authToken (required), chainName (required).

getTransactionLogsForAddressC
Read-only

Get logs for transaction created by the provided address

Inputs: authToken (required), chainName (required), contractAddress (required).

getTransactionsForAddressB
Read-only

Get transactions to and from the wallet address

Inputs: address (required), authToken (required), chainName (required).

getWalletTransactionSummaryB
Read-only

Get a summary of transactions for a specific wallet address

Inputs: authToken (required), chainName (required), walletAddress (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.7/5.0

    Scored across 26 tools

    Disambiguation2/5

    Many tools have overlapping functionality, e.g., getERC20Balance, getTokenBalance, getHistoricalBalance, and getTokenBalancePortfolio all relate to balances. Similarly, getRecentTransactions, getLatestTransactions, getTransactionsForAddress, and getBulkTransactions all fetch transactions, making it difficult for an agent to select the correct tool.

    Naming Consistency4/5

    All tools consistently follow the 'get' + CamelCase noun phrase pattern (e.g., getERC20Balance, getBlockHeights, getTokenHolders). Minor variations like getNFTtokensByAddress with mixed casing are slight deviations, but the overall naming convention is uniform and predictable.

    Tool Count2/5

    With 26 tools, the server is over the recommended range and feels bloated. Many tools could be consolidated (e.g., balance queries could be unified into fewer endpoints), and the redundancy makes the tool set heavier than necessary for its domain.

    Completeness4/5

    The blockchain data retrieval domain is well covered, including blocks, transactions, balances, transfers, logs, and token holders. Minor gaps such as a direct native balance endpoint or token metadata search can be worked around, but core operations are present.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers