Content
# 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
| Network | Chain ID | Minimum Deposit |
|---------|----------|----------------|
| Ethereum | 1 | $50 |
| Polygon | 137 | $2.5 |
| Arbitrum | 42161 | $2.5 |
| Base | 8453 | $2.5 |
| **Katana** | **747474** | **Destination** |
## 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):
```json
{
"mcpServers": {
"katana-mcp": {
"command": "npx",
"args": ["katana-mcp"],
"env": {
"WALLET_PRIVATE_KEY": "your_private_key_here"
}
}
}
}
```
## 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:**
```
Bridge 100 USDC from Ethereum to Katana
```
### Get Token Balances
**Tool**: `getTokenBalances`
Check your token balances on Katana network.
**Parameters:**
- `walletAddress` (optional): Wallet address to check
**Example Usage:**
```
Show my token balances on Katana
```
### Yearn Vault Operations
#### Get Vault Information
**Tool**: `getYearnVaultInfo`
Get detailed information about available Yearn vaults.
**Example Usage:**
```
Show me all available Yearn vaults on Katana
```
#### 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:**
```
Deposit 1000 USDC into the USDC vault
```
#### 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:**
```
Show my Yearn vault positions
```
### 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:**
```
Get a quote to swap 1 ETH for USDC with 0.5% slippage
```
#### 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:**
```
Swap 0.1 ETH for USDC with 2% slippage tolerance
```
## 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**
```bash
git clone https://github.com/yourusername/katana-mcp-server.git
cd katana-mcp-server
```
2. **Install dependencies**
```bash
pnpm install
```
3. **Environment Configuration**
Create a `.env` file in the root directory:
```env
WALLET_PRIVATE_KEY=your_private_key_here
```
⚠️ **Security Warning**: Never commit your private key to version control. Keep your `.env` file secure and private.
4. **Build the project**
```bash
pnpm run build
# or
npm run build
```
5. **Start the server**
```bash
pnpm run start
# or
npm run start
```
### Project Structure
```
katana-mcp-server/
├── index.ts # Main server implementation
├── dist/ # Compiled JavaScript
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
└── README.md
```
## 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
