Kaia MCP Server

Production-ready Model Context Protocol (MCP) server for the Kaia blockchain. Exposes 26 tools, 5 resources, and 6 prompts for balance, transactions, blocks, tokens, NFTs, contracts, network info, and wallet utilities.

Installation

npm install -g kaia-mcp
# or
npx kaia-mcp

Quick start

stdio (default) — run and connect via stdin/stdout (e.g. Claude Desktop, Cursor):

npx kaia-mcp
# or
npx kaia-mcp --transport stdio

HTTP — run Streamable HTTP transport on a port:

npx kaia-mcp --transport http --port 3100

Tools (26)

| Tool | Description | |------|-------------| | get_kaia_balance | Get KAIA balance for an address | | get_account_info | Get account summary: balance, tx count, nonce | | get_account_tokens | List ERC-20 token holdings for an address | | get_account_nfts | List NFT holdings for an address | | get_transaction | Get transaction by hash | | get_transaction_receipt | Get transaction receipt and status | | get_account_transactions | List recent transactions for an address | | estimate_gas | Estimate gas for a transaction | | get_block_number | Current block number | | get_block | Get block by number or tag | | get_block_rewards | Block rewards for a block | | get_token_info | Token metadata (name, symbol, supply) | | get_token_holders | Top token holders | | get_token_transfers | Token transfer history | | get_token_allowance | ERC-20/KIP-7 allowance (owner/spender) for DeFi | | get_nft_info | NFT collection info | | get_nft_item | Single NFT item (owner, metadata) | | get_nft_transfers | NFT transfer history | | read_contract | Read contract view/pure function | | get_contract_abi | Verified contract ABI from KaiaScan | | get_contract_source | Verified contract source from KaiaScan | | get_gas_price | Current gas price | | get_kaia_price | KAIA price (USD, BTC, stats) from KaiaScan | | get_chain_info | Chain id and name (mainnet/kairos) | | generate_wallet | Generate a new wallet keypair (address + private key hex) | | encode_function_data | Encode contract call data from ABI and args |

Resources (5)

| URI | Description | |-----|-------------| | kaia://mainnet/status | Mainnet status: block height, gas price, KAIA price | | kaia://kairos/status | Kairos testnet status | | kaia://mainnet/tokens/popular | Popular mainnet token addresses with name/symbol | | kaia://mainnet/top-accounts | Top 100 KAIA holders | | kaia://docs/rpc-methods | Static reference of Kaia RPC methods |

Prompts (6)

| Name | Args | Description | |------|------|-------------| | analyze-wallet | address, network? | Analyze wallet: balance, txs, tokens | | investigate-transaction | txHash | Investigate tx: status, gas, transfers | | token-research | contractAddress, network? | Research token: supply, holders, activity | | nft-lookup | contractAddress, tokenId, network? | Look up NFT: owner, metadata, history | | gas-report | network? | Gas report: price, history, recommendations | | smart-contract-audit | contractAddress, network? | Review contract: ABI, source, type |

Configuration

Environment variables (see .env.example):

| Variable | Description | Default | |----------|-------------|---------| | KAIA_RPC_URL | Kaia mainnet RPC endpoint | https://public-en.node.kaia.io | | KAIA_KAIROS_RPC_URL | Kairos testnet RPC | https://public-en-kairos.node.kaia.io | | KAIASCAN_API_KEY | KaiaScan API key (optional) | — | | KAIA_DEFAULT_NETWORK | mainnet or kairos | mainnet | | LOG_LEVEL | debug, info, warn, error | info | | RATE_LIMIT_RPC | Max RPC requests per second | 10 | | RATE_LIMIT_KAIASCAN | Max KaiaScan requests per second | 5 | | RPC_TIMEOUT_MS | RPC request timeout (ms) | 30000 | | KAIASCAN_TIMEOUT_MS | KaiaScan request timeout (ms) | 15000 |

MCP client setup

Cursor — add to Cursor MCP settings (e.g. ~/.cursor/mcp.json or project MCP config):

{
  "mcpServers": {
    "kaia": {
      "command": "npx",
      "args": ["kaia-mcp"],
      "env": {}
    }
  }
}

Claude Desktop — in Claude Desktop config (e.g. ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "kaia": {
      "command": "npx",
      "args": ["kaia-mcp"],
      "env": {}
    }
  }
}

Override env as needed, e.g. "env": { "KAIA_RPC_URL": "https://your-rpc.io", "KAIASCAN_API_KEY": "your-key" }.

Links

• Kaia docs
• KaiaScan API

Programmatic use

import { createKaiaMcpServer, runKaiaMcpServer } from "kaia-mcp";

// Get the MCP Server instance (e.g. for custom transport)
const server = createKaiaMcpServer();

// Run over stdio (CLI default)
await runKaiaMcpServer();

For HTTP:

import { runKaiaMcpServerHttp } from "kaia-mcp";
await runKaiaMcpServerHttp(3100);

Docker

docker build -t kaia-mcp .
docker run -p 3100:3100 -e KAIA_RPC_URL=https://public-en.node.kaia.io kaia-mcp

Server listens on port 3100 (Streamable HTTP transport). Override env as needed.

Connecting to the Docker server

The container runs the HTTP transport (not stdio), so clients must connect by URL.

Cursor — in MCP settings (e.g. ~/.cursor/mcp.json or project MCP config), add a server entry with url:

{
  "mcpServers": {
    "kaia": {
      "url": "http://localhost:3100"
    }
  }
}

If your client expects a path, use http://localhost:3100/mcp. Restart Cursor after changing MCP config.

Claude Desktop — if your Claude Desktop build supports remote MCP URLs, use the same url in its MCP config.

Test from the host (with the container running):

curl -s -X POST http://localhost:3100 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq

You should see a list of tools. Replace localhost with your machine’s IP or hostname when connecting from another device.

License

MIT