@initia/mcp

MCP server and CLI for the Initia blockchain ecosystem. Tools for querying chain state, managing assets, and executing transactions across Initia L1 and L2 rollups (MiniEVM, MiniMove, MiniWasm).

Two interfaces, one codebase:

• @initia/mcp — MCP server (stdio transport, for Claude Desktop / LLM agents)
• initctl — CLI (for humans and scripts)

Quick Start

npm install
npm run build

CLI (initctl)

# Global install
npm install -g .
initctl chain list

# Or run directly without global install
node dist/cli.js chain list

# Or via npx (after npm install)
npx initctl chain list

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "initia": {
      "command": "npx",
      "args": ["-y", "@initia/mcp"],
      // optional — see Environment Variables below
      "env": {
        "INITIA_KEY": "your mnemonic words ...",
        "INITIA_NETWORK": "mainnet"
      }
    }
  }
}

Claude Code

claude mcp add initia -s user -- npx -y @initia/mcp

# optional — see Environment Variables below
claude mcp add initia -s user \
  -e INITIA_KEY="your mnemonic words ..." \
  -e INITIA_NETWORK=mainnet \
  -- npx -y @initia/mcp

Codex

Add to codex.json (or pass via codex --mcp-config codex.json):

{
  "mcpServers": {
    "initia": {
      "command": "npx",
      "args": ["-y", "@initia/mcp"],
      // optional — see Environment Variables below
      "env": {
        "INITIA_KEY": "your mnemonic words ...",
        "INITIA_NETWORK": "mainnet"
      }
    }
  }
}

Gemini CLI

Add to .gemini/settings.json:

{
  "mcpServers": {
    "initia": {
      "command": "npx",
      "args": ["-y", "@initia/mcp"],
      // optional — see Environment Variables below
      "env": {
        "INITIA_KEY": "your mnemonic words ...",
        "INITIA_NETWORK": "mainnet"
      }
    }
  }
}

CLI

# Query
initctl chain list
initctl token search --symbol USDC
initctl move view --module-address 0x1 --module-name coin --function-name balance --args '["0x1"]'

# Transaction (interactive confirm)
initctl bank send --to init1abc... --amount 1000000 --denom uinit

# Transaction (skip confirm)
initctl bank send --to init1abc... --amount 1000000 --denom uinit --yes

# JSON output (for scripts)
initctl token search --symbol INIT --json

# Shell completion
eval "$(initctl completion bash)"   # bash
eval "$(initctl completion zsh)"    # zsh
initctl completion fish | source    # fish

Environment Variables

Variable	Required	Default	Description
INITIA_KEY	No	—	Mnemonic (12/24 words), hex private key (0x...), or "ledger"
INITIA_KEY_INDEX	No	0	HD derivation index (for mnemonic/ledger)
INITIA_LEDGER_APP	No	ethereum	Ledger app: ethereum or cosmos
INITIA_NETWORK	No	mainnet	mainnet or testnet
AUTO_CONFIRM	No	false	Skip confirmation for mutations (MCP only)
INITIA_LOG_LEVEL	No	info	debug, info, warn, error
INITIA_USE_SCAN_API	No	false	Use Scan API for enhanced chain data

Without a signer key, read-only tools still work. Mutation tools return SIGNER_REQUIRED.

Tools (107)

Chain & Account (10)

Tool	Description
chain_list	List all supported chains (L1 + L2 rollups)
chain_capabilities	Get chain VM type, features, and endpoints
chain_gas_prices	Current on-chain gas prices (L1 or L2)
account_get	Account info and balances
portfolio_get	Aggregated balances across all chains
address_validate	Validate bech32 or EVM address format
address_convert	Convert between bech32 and hex
delegation_get	Staking delegations, rewards, and unbonding
distribution_rewards	Pending staking rewards across validators
simulate_tx	Simulate a transaction and estimate gas

Token & Denom (7)

Tool	Description
token_search	Search tokens by symbol across all chains
token_list	List registered tokens on a chain
token_info	Token metadata (name, symbol, decimals) for any type
token_balance	Token balance for native, ERC20, CW20, or Move FA
amount_format	Format raw amount with decimals
denom_classify	Classify denomination type (native, ibc, evm, etc.)
denom_metadata	On-chain bank module metadata

Transaction (3)

Tool	Description
tx_get	Get transaction by hash with VM-aware decoding
tx_search	Search transactions (CometBFT query syntax)
tx_by_address	Recent transactions for an address

Validator & Staking (7)

Tool	Description
validator_list	List validators with status and voting power
validator_get	Detailed validator information
staking_pool	Network bonded/unbonded token totals
staking_annual_provisions	Current annual token provisions (inflation)
staking_manage	Delegate, undelegate, redelegate, or claim rewards
governance_vote	Vote on a governance proposal
proposal_list / proposal_get	List or get governance proposals

Bridge (14)

Tool	Description
bridge_route	Find optimal cross-chain transfer route
bridge_execute	Execute a cross-chain transfer via router
bridge_transfer_status	Track cross-chain transfer progress
bridge_list_chains	List bridgeable L2 chains
bridge_routable_assets	List assets available for routing
bridge_deposit / bridge_withdraw	Direct L1↔L2 OPInit deposit/withdraw
bridge_withdrawals / bridge_withdrawal_status	Query withdrawal status
opbridge_list / opbridge_get	OPInit bridge configuration
opbridge_token_pairs	L1↔L2 token pair mappings
opbridge_token_pair_by_l1_denom / opbridge_token_pair_by_l2_denom	Token pair lookup

IBC (3)

Tool	Description
ibc_channels	List IBC channels or find channel between two chains
ibc_denom_hash	Compute IBC denomination hash from path
ibc_transfer	Send tokens via IBC

Username (4)

Tool	Description
username_resolve	Resolve .init names ↔ addresses
username_record	Full .init username record
username_metadata	NFT metadata for .init username
username_check	Check username availability

Move VM (14)

Tool	Description
move_modules	List modules deployed at an address
move_module_abi	Get module ABI (functions, structs)
move_resources	List resources held by an address
move_resource_get	Query a specific resource
move_view	Call a view function (read-only)
move_execute	Execute an entry function
move_publish / move_script	Deploy module or run script
move_table_entry	Query a table entry
move_dex_pairs	List DEX liquidity pool pairs
move_denom_metadata / move_metadata_denom	Denom ↔ metadata conversion
move_bcs_encode / move_bcs_decode	BCS serialization utilities

EVM (10)

Tool	Description
evm_call	Call a contract function (read-only)
evm_send	Send a state-changing transaction
evm_deploy	Deploy a contract
evm_get_logs	Query event logs
evm_get_tx_receipt	Get transaction receipt
evm_get_block	Get block information
evm_get_code	Get contract bytecode (Minievm only)
evm_get_storage_at	Read storage slot (Minievm only)
evm_decode_revert	Decode revert reason
evm_decode_logs	Decode event logs with ABI

CosmWasm (12)

Tool	Description
wasm_query	Query a smart contract
wasm_execute	Execute a smart contract function
wasm_store_code	Upload contract bytecode
wasm_instantiate	Instantiate a contract
wasm_migrate	Migrate to a new code ID
wasm_update_admin / wasm_clear_admin	Admin management
wasm_contract_info / wasm_code_info	Contract/code metadata
wasm_contracts_by_code	List contracts from a code ID
wasm_contract_history	Migration history
wasm_raw_state	Raw key-value state

VIP (16)

Tool	Description
vip_stage_info	Current VIP stage and timing
vip_positions	Lock-staking positions
vip_voting_power	Gauge voting power
vip_vesting_positions	Vesting schedules with reward breakdowns
vip_vote_info	Vote allocations per bridge
vip_claimable_rewards	Claimable VIP rewards
vip_delegate / vip_undelegate / vip_redelegate	Lock-staking management
vip_extend_lock	Extend lock duration
vip_gauge_vote / vip_gauge_vote_by_amount	Gauge voting
vip_claim_rewards / vip_claim_staking_rewards	Reward claiming
vip_provide_and_delegate	LP + lock-delegate in one tx
vip_stableswap_provide_and_delegate	Stableswap LP + lock-delegate

Event Parsing (3)

Tool	Description
event_parse_tx	Parse Cosmos events from a transaction
event_parse_move	Decode Move module events
event_parse_wasm	Decode CosmWasm contract events

Ledger (2)

Tool	Description
ledger_status	Check Ledger device connection
ledger_verify_address	Display address on device for verification

Bank (1)

Tool	Description
bank_send	Send tokens (supports batch sends)

Architecture

src/
├── index.ts              # MCP server entry point (stdio)
├── cli.ts                # CLI entry point (initctl)
├── tools/
│   ├── registry.ts       # ToolRegistry — shared by MCP and CLI
│   ├── groups.ts         # Group definitions (24 groups)
│   ├── index.ts          # Side-effect imports for all tool files
│   ├── tx-executor.ts    # Mutation flow (dry-run → simulate → broadcast)
│   ├── vm-guard.ts       # VM compatibility checks
│   └── *.ts              # Tool modules (registry.register() calls)
├── mcp/
│   └── adapter.ts        # Registry → McpServer binding
├── cli/
│   ├── adapter.ts        # Registry → citty commands + zodToCittyArgs
│   ├── format.ts         # TTY / JSON output formatting
│   ├── confirm.ts        # Mutation y/N prompt
│   └── completion.ts     # Shell completion (bash/zsh/fish)
├── initia/
│   └── chain-manager.ts  # Chain context creation, caching
├── config/               # Environment config, chain aliases
├── schemas/              # Shared Zod parameter schemas
├── errors.ts             # Typed error codes
├── response.ts           # Response serialization
└── logger.ts             # Structured JSON logging

Tools are registered once in a transport-agnostic ToolRegistry. The MCP and CLI adapters consume the same registry independently — adding a tool to a *.ts file automatically exposes it in both interfaces.

Smart Defaults

• Validator by name: Tools accepting a validator address also accept the moniker name (case-insensitive, auto-resolved)
• "me" address: Address parameters accept "me", "self", "my", or "signer" to resolve to the configured signer
• VM guard: Contract tools enforce VM compatibility — calling move_view on a MiniEVM chain returns a WRONG_VM error with suggested alternatives

Development

npm run dev          # Run MCP server with tsx (hot reload)
npm test             # Unit + integration tests
npm run test:smoke   # E2E tests against testnet
npm run lint         # ESLint + tsc --noEmit

License

Apache-2.0