@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

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

Tools (107)

Chain & Account (10)

Token & Denom (7)

Transaction (3)

Validator & Staking (7)

Bridge (14)

IBC (3)

Username (4)

Move VM (14)

EVM (10)

CosmWasm (12)

VIP (16)

Event Parsing (3)

Ledger (2)

Bank (1)

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