Somnia MCP server

somnia mcp serves Somnia Markets to AI agents over the Model Context Protocol: read tools for markets, books, positions, prices and the Explorer, and a guide to every Somnia CLI command. It never signs or sends a transaction.

Somnia Markets as tools for your agent.

The Somnia MCP server ships inside the Somnia CLI as somnia mcp. It speaks the Model Context Protocol over stdio, so Claude Code, Codex, Cursor and any other MCP client can read markets, order books, positions, prices and the Explorer, and find the right CLI command for anything else.

The server never signs or sends anything. Every transaction goes through the CLI, under a signer you choose, so nothing touches funds without the key you set up.

Set it up

The server needs Node.js 22 or newer. Your MCP client starts it, so there is nothing to run yourself.

Claude Code:

claude mcp add somnia -- npx -y @somnia-chain/cli mcp

Codex:

codex mcp add somnia -- npx -y @somnia-chain/cli mcp

Cursor, Claude Desktop and other clients that take a JSON config (in Cursor, .cursor/mcp.json in your project or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "somnia": {
      "command": "npx",
      "args": ["-y", "@somnia-chain/cli", "mcp"]
    }
  }
}

If you installed the CLI with npm install -g @somnia-chain/cli, use somnia mcp as the command instead of npx:

claude mcp add somnia -- somnia mcp

The read tools go to mainnet unless a call names a network. To make testnet the default, add --network testnet after mcp, or set SOMNIA_NETWORK=testnet in the server's environment. --rpc-url, --indexer-url, --oracle-url and --explorer-url point the tools at other endpoints than the preset's.

What your agent can do

Each read tool runs the matching CLI command and returns its JSON along with the command line, so the agent learns the CLI as it goes.

Tool	What it reads
`markets`	Markets of every kind, newest first
`spot_book`	A spot pool's resting book, and its tick and lot grid
`spot_portfolio`	A wallet's spot open orders, pending stop orders and recent trades
`binary_markets`	Binary markets trading now, past or all, with filters
`binary_market`	One binary market: its indexed row, live state, ids and payout
`binary_positions`	An account's open binary positions, with cost basis, mark and PnL
`perp_markets`	Perp markets, and whether each is tradeable
`perp_account`	A cross-margin account's collateral, equity, margin and positions
`token_balance`	An account's balance of an ERC-20, or of an ERC-6909 id
`price`	An asset's oracle feed, and its latest spot and mark price
`fills`	An account's fills as maker or taker, newest first
`venue_health`	A grade for the venue (ok, degraded or down) from the indexer, chain and price feed
`explorer_address`	An address on the Explorer: balance, contract or account, creator, token
`explorer_transaction`	A transaction: status, block, sender, recipient, value, fee and token transfers
`explorer_block`	A block by number or hash
`explorer_token`	A token: name, symbol, type, decimals, supply and holders
`explorer_logs`	Event logs of a transaction or a contract
`explorer_search`	Search for an address, transaction, block, token or contract

Three more tools cover everything else:

somnia_find finds the CLI command for a task described in plain words, such as "place a spot order" or "perp funding history".
somnia_help shows any command's --help: what it does and prints, its flags and examples.
somnia_feedback tells the Somnia team about a problem with the CLI or these tools, as somnia feedback does. Pass messageOnly: true to send the agent's words alone.

Transactions

The CLI has about 190 commands, including every transaction: orders, cancels, deposits, transfers and lending. For those, the server points the agent to the CLI, which the agent runs from a shell. The CLI signs with the account your environment selects, such as a key in your system keychain, and prints JSON with the transaction's hash, status and block. See Signing for every way to give it a key.

To review before anything is sent, export the build signer in the shell you start the agent from, so the CLI commands the agent runs inherit it, and keep any key out of that shell. Put your account's address in place of <address>:

unset SOMNIA_PRIVATE_KEY SOMNIA_SESSION_SEED
export SOMNIA_SIGNER=build:<address>

Setting it only in the MCP server's config doesn't reach the agent's shell. The agent's write commands then print unsigned transactions, which you sign with somnia tx sign in a separate shell that has your key (for example SOMNIA_SIGNER=keychain:<name>), then send with somnia tx submit. See Offline signing.

Try writes on the Global testnet first, with STT from the testnet faucet.

Telemetry

The CLI's usage telemetry is off until the user opts in, and somnia mcp never asks. An agent should not turn it on by itself: it asks its user once, says what is shared, and runs somnia telemetry enable only on a clear yes. See Usage telemetry.

Docs for agents

To give an agent the docs as well, point it at llms.txt, or llms-full.txt for every page in one file. The Explorer's llms.txt lists its pages and APIs, which need no key.

Edit this page