KAIA-MCP Server

AI × DeFi Infrastructure for the Kaia Ecosystem

The KAIA-MCP Server enables AI agents to interact directly with DeFi protocols on the KAIA blockchain.
Built on the Model Context Protocol (MCP), it connects tools like Claude Desktop or Cursor.ai with live blockchain data and transaction execution.

Features

Multi-Protocol Support

• Lending: KiloLend (Compound v2 fork) for supply, borrow, and repay
• DEX: DragonSwap V3 for quotes and swaps
• Price API: Real-time token prices from CoinMarketCap & CoinGecko API
• AI-Managed Vaults: Automated cross-protocol strategies to boost yield (planned)
• Market Intelligence: Real-time APYs, utilization, and TVL
• Smart Wallet: Unified position and balance tracking

Using with Claude Desktop

1. Install Claude Desktop if you haven't already
2. Open Claude Desktop settings
3. Add the KAIA MCP client to your configuration:

{
  "mcpServers": {
    "kaia-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@tamago-labs/kaia-mcp"
      ],
      "env": {
        "KAIA_RPC_URL": "https://public-en.node.kaia.io",
        "KAIA_AGENT_MODE": "transaction",
        "KAIA_PRIVATE_KEY": "YOUR_PRIVATE_KEY"
      },
      "disabled": false
    }
  }
}

Agent Modes

Read-Only Mode (Default)

• Purpose: Safe exploration and data analysis without transaction capabilities
• Use Case: Perfect for research, market analysis, and monitoring positions
• Capabilities: Query market data, check wallet balances, monitor positions, get swap quotes
• Security: No private key required - completely safe for data access
• Configuration: Set KAIA_AGENT_MODE to "readonly" or omit the private key

Transaction Mode

• Purpose: Full DeFi operations with the ability to execute transactions
• Use Case: Active trading, lending, borrowing, and portfolio management
• Capabilities: All read-only features plus execute transactions, supply/borrow assets, transfer tokens, execute DEX swaps
• Security: Requires KAIA_PRIVATE_KEY - ensure secure key management
• Configuration: Set KAIA_AGENT_MODE to "transaction" and provide a valid private key

Architecture

This MCP server follows a clean, modular architecture designed for multi-protocol support:

src/
├── agent/
│   └── wallet.ts            # Unified WalletAgent for all operations
├── mcp/                     # MCP tool definitions and implementations
│   ├── index.ts             # Main MCP server entry point and tool registry
│   ├── kilolend/           # KiloLend protocol tools
│   ├── dragonswap/          # DragonSwap V3 protocol tools
│   ├── price-api/          # Price API tools for token prices
│   └── wallet/              # General wallet operations
├── tools/                  # Core utility functions
│   └── price-api/          # Price API core functions
├── contracts/               # Smart contract interfaces and ABIs
│   ├── comptroller.ts       # KiloLend Comptroller contract
│   ├── ctoken.ts           # KiloLend cToken contracts
│   ├── erc20.ts            # Standard ERC-20 interface
│   ├── wkaia.ts            # WKAIA contract interface
│   └── dragonswap/         # DragonSwap contract ABIs
├── utils/                  # Utility functions and helpers
│   ├── errors.ts           # Error handling classes
│   ├── formatting.ts       # Token amount formatting utilities
│   └── validation.ts       # Input validation functions
├── config.ts               # Configuration management and environment setup
├── types.ts                # TypeScript type definitions
└── index.ts                # Main server entry point

Installation

npm install
npm run build

Configuration

Environment Variables

Create a .env file based on .env.example:

# Required
KAIA_RPC_URL="https://public-en.node.kaia.io"         # KAIA Mainnet RPC URL

# Optional
KAIA_PRIVATE_KEY="your_private_key_here"             # Wallet private key (for transaction mode)
KAIA_AGENT_MODE="readonly"                           # "readonly" or "transaction" (defaults to readonly)
KAIA_NETWORK="kaia"                                  # Network (only kaia supported currently)

Available Tools

Wallet Tools

Read-Only Tools

| Tool | Description | |------|-------------| | get_wallet_info | Get wallet information and token balances |

Transaction Tools

| Tool | Description | |------|-------------| | send_native_token | Send native KAIA tokens | | send_erc20_token | Send ERC-20 tokens | | wrap_kaia | Wrap KAIA to WKAIA | | unwrap_kaia | Unwrap WKAIA to KAIA | | check_allowance | Check token allowance for operations | | approve_token | Approve tokens for operations |

KiloLend Tools

Read-Only Tools

| Tool | Description | |------|-------------| | get_account_liquidity | Check account liquidity and health factor | | get_markets | Get all lending markets with rates | | get_protocol_stats | Get protocol statistics and TVL |

Transaction Tools

| Tool | Description | |------|-------------| | enter_market | Enter markets to enable collateral usage | | supply_to_market | Supply assets to lending market | | borrow_from_market | Borrow from lending market | | repay_borrow | Repay borrowed positions | | redeem_tokens | Redeem cTokens (withdraw by cToken amount) | | redeem_underlying | Redeem underlying tokens (withdraw by underlying amount) |

Price API Tools

Read-Only Tools

| Tool | Description | |------|-------------| | get_all_prices | Get all available prices from KiloLend price API | | get_token_prices | Get prices for specific tokens (e.g., ['KAIA', 'BTC', 'ETH']) | | get_kaia_ecosystem_prices | Get KAIA ecosystem token prices only (KAIA, BORA, MBX, SIX, SOMNIA, stKAIA) | | get_major_crypto_prices | Get major cryptocurrency prices (BTC, ETH) | | get_quick_prices | Quick price overview of KAIA, BTC, and ETH |

DragonSwap Tools

Read-Only Tools

| Tool | Description | |------|-------------| | dragonswap_get_pool_info | Get DragonSwap pool information | | dragonswap_get_swap_quote | Get swap quotes without executing | | dragonswap_get_route | Get best routing path for swaps (supports multi-hop) |

Transaction Tools

| Tool | Description | |------|-------------| | dragonswap_execute_swap | Execute token swaps on DragonSwap |

Supported Tokens

KiloLend Supported Tokens

• KAIA: Native KAIA token
• USDT: Tether USD (0xd077a400968890eacc75cdc901f0356c943e4fdb)
• SIX: SIX token (0xEf82b1C6A550e730D8283E1eDD4977cd01FAF435)
• BORA: BORA token (0x02cBE46fB8A1F579254a9B485788f2D86cAD51aa)
• MBX: MARBLEX token (0xD068c52d81f4409B9502dA926aCE3301cc41f623)
• stKAIA: Lair Staked KAIA (0x42952B873ed6f7f0A7E4992E2a9818E3A9001995)

DragonSwap Supported Tokens

• KAIA: Native token
• WKAIA: Wrapped KAIA (0x19aac5f612f524b754ca7e7c41cbfa2e981a4432)
• USDT: Official USDT(0xd077a400968890eacc75cdc901f0356c943e4fdb)
• USDT: Wormhole USDT(0x5c13e303a62fc5dedf5b52d66873f2e59fedadc2)
• BORA: BORA Token (0x02cBE46fB8A1F579254a9B485788f2D86cAD51aa)
• MBX: MARBLEX Token (0xD068c52d81f4409B9502dA926aCE3301cc41f623)
• stKAIA: Lair Staked KAIA (0x42952B873ed6f7f0A7E4992E2a9818E3A9001995)

Future Protocol Support

We're actively working on adding support for:

• Additional Lending Protocols: More lending platforms
• Staking Protocols: Liquid staking and Lair Finance integration
• Cross-Chain Messaging: Chainlink CCIP for cross-chain operations
• Yield Farming: Cross-protocol yield optimization

Contract Addresses

Kaia Mainnet

KiloLend (Compound v2)

• Comptroller: 0x0B5f0Ba5F13eA4Cb9C8Ee48FB75aa22B451470C2
• Markets:
  • cUSDT: 0x498823F094f6F2121CcB4e09371a57A96d619695
  • cSIX: 0xC468dFD0C96691035B3b1A4CA152Cb64F0dbF64c
  • cBORA: 0x7a937C07d49595282c711FBC613c881a83B9fDFD
  • cMBX: 0xE321e20F0244500A194543B1EBD8604c02b8fA85
  • cKAIA: 0x98Ab86C97Ebf33D28fc43464353014e8c9927aB3
  • cStKAIA: 0x0BC926EF3856542134B06DCf53c86005b08B9625

DragonSwap V3

• Router: 0xA324880f884036E3d21a09B90269E1aC57c7EC8a
• Quoter V2: 0x673d88960D320909af24db6eE7665aF223fec060
• Factory: 0x7431A23897ecA6913D5c81666345D39F27d946A4

Troubleshooting

If you're using Ubuntu or another Linux environment with NVM, you'll need to manually configure the path. Follow these steps:

1. Install the KAIA MCP under your current NVM-managed Node.js version.

npm install -g @tamago-labs/kaia-mcp

2. Due to how NVM installs libraries, you may need to use absolute paths in your config. Replace the example values below with your actual username and Node version:

{
  "mcpServers": {
    "kaia-mcp": {
      "command": "/home/YOUR_NAME/.nvm/versions/node/YOUR_NODE_VERSION/bin/node",
      "args": [
        "/home/YOUR_NAME/.nvm/versions/node/YOUR_NODE_VERSION/bin/@tamago-labs/kaia-mcp"
      ],
      "env": {
        "KAIA_RPC_URL": "https://public-en.node.kaia.io",
        "KAIA_AGENT_MODE": "transaction",
        "KAIA_PRIVATE_KEY": "YOUR_PRIVATE_KEY"
      }
    }
  }
}

3. Restart Claude Desktop and it should work now.

Environment Variable Issues

If you encounter issues with environment variables not being recognized:

1. Check required variables: Make sure KAIA_RPC_URL is always set
2. Verify mode settings: KAIA_AGENT_MODE should be either "readonly" or "transaction"
3. Private key format: KAIA_PRIVATE_KEY must be 64 hex characters (with or without 0x prefix)
4. Debug logging: The server will log all configuration on startup to stderr

Work with Local Files

When working with local files especially when using KAIA CLI tools for smart contract development to create, build, and test a Move package on your machine—you'll need to import an additional MCP server library of filesystem made by Claude team. Use with:

"filesystem": {
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-filesystem",
    "${workspaceFolder}"
  ],
  "env":{
        
  },
  "disabled": false
}

workspaceFolder refers to your working directory. You can provide more than one argument. Subfolders or specific files can then be referenced in your AI prompt.

If you're using Linux and encounter issues during setup, please refer to the troubleshooting section.

License

MIT License - see LICENSE file for details.