Katana MCP Server

A Model Context Protocol (MCP) server for interacting with the Katana network, providing seamless cross-chain bridging, DeFi operations, and Yearn vault management through AI assistants.

Features

Cross-Chain Bridging

• Bridge assets from Ethereum, Polygon, Arbitrum, and Base to Katana

• Automatic deposit address generation

• Support for major tokens (USDC, USDT, ETH, DAI, etc.)

SushiSwap Integration

• Get real-time swap quotes

• Execute token swaps with customizable slippage

• Support for all major tokens on Katana

Yearn Vault Management

• Deposit into yield-generating vaults

• Withdraw from vault positions

• View vault performance and user positions

Portfolio Management

• Check token balances across all assets

• Track Yearn vault positions

• Monitor transaction history

Supported Networks

Supported Tokens

Katana Native Tokens

• ETH - Ethereum

• USDC - USD Coin

• USDT - Tether USD

• WBTC - Wrapped Bitcoin

• AUSD - Aave USD

• USDS - USDS Stablecoin

Yearn Vaults Available

• yvUSDC - USDC Vault

• yvETH - ETH Vault

• yvUSDT - USDT Vault

• yvWBTC - WBTC Vault

• yvAUSD - AUSD Vault

Installation

Prerequisites

• Node.js 18.0.0 or higher

• npm or pnpm package manager

• A wallet private key with funds on supported networks

MCP Configuration

Add this server to your MCP-compatible AI assistant (like Claude Desktop):

Available Tools

Bridge Assets

Tool: bridgeAssets

Bridge tokens from supported chains to Katana network.

Parameters:

• asset (string): Token symbol (e.g., 'USDC', 'ETH')

• chain (string): Source chain ('ethereum', 'polygon', 'arbitrum', 'base')

• amount (string): Amount to bridge (e.g., '100')

Example Usage:

Get Token Balances

Tool: getTokenBalances

Check your token balances on Katana network.

Parameters:

• walletAddress (optional): Wallet address to check

Example Usage:

Yearn Vault Operations

Get Vault Information

Tool: getYearnVaultInfo

Get detailed information about available Yearn vaults.

Example Usage:

Deposit to Vault

Tool: depositToYearnVault

Deposit tokens into yield-generating vaults.

Parameters:

• token (string): Token to deposit ('USDC', 'ETH', etc.)

• amount (string): Amount to deposit

• vaultTarget (string): Target vault ('USDC', 'ETH', 'WBTC', 'USDT', 'AUSD')

Example Usage:

Withdraw from Vault

Tool: withdrawFromYearnVault

Withdraw tokens from vault positions.

Parameters:

• vaultAddress (string): Vault contract address

• amount (string): Amount to withdraw

• withdrawType (string): 'assets' or 'shares'

Get Vault Positions

Tool: getUserYearnPositions

View your current vault positions and yields.

Example Usage:

SushiSwap Integration

Get Swap Quote

Tool: getSushiQuote

Get a quote for token swaps on SushiSwap.

Parameters:

• tokenIn (string): Input token

• tokenOut (string): Output token

• amount (string): Amount to swap

• maxSlippage (number): Maximum slippage percentage

Example Usage:

Execute Swap

Tool: executeSushiSwap

Execute a token swap on SushiSwap.

Parameters:

• tokenIn (string): Input token

• tokenOut (string): Output token

• amount (string): Amount to swap

• maxSlippage (number): Maximum slippage percentage

Example Usage:

Error Handling

The server includes comprehensive error handling for common issues:

• Insufficient Balance: Clear messages about available vs required amounts

• Network Issues: Automatic retry logic and helpful troubleshooting

• Slippage Protection: Configurable slippage tolerance with sensible defaults

• Gas Estimation: Automatic gas limit calculation with safety margins

Security Features

• Private Key Management: Secure environment variable handling

• Transaction Simulation: Pre-execution validation to prevent failed transactions

• Allowance Optimization: Efficient token approval management

• Slippage Protection: Configurable MEV protection

Local Setup

1. Clone the repository

2. Install dependencies

3. Environment Configuration Create a .env file in the root directory:

⚠️ Security Warning: Never commit your private key to version control. Keep your .env file secure and private.

4. Build the project

5. Start the server

Project Structure

Contributing

We welcome contributions! Please see our contributing guidelines:

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

Troubleshooting

Common Issues

"WALLET_PRIVATE_KEY not found"

• Ensure your .env file contains your private key

• Verify the environment variable is correctly set

"Insufficient balance" errors

• Check your token balance on the source chain

• Ensure you have enough for gas fees

• Verify minimum deposit requirements are met

Transaction failures

• Try increasing slippage tolerance

• Check network congestion

• Ensure sufficient gas token balance

Bridge issues

• Verify the token is supported on the source chain

• Check minimum deposit amounts

• Ensure wallet has sufficient balance

Getting Help

• Issues: Open an issue on GitHub with detailed error messages

• Discussions: Use GitHub Discussions for questions and feature requests

• Documentation: Check this README and inline code comments