jayeshchowdary/lifi-mcp

LiFi MCP Server (Python)

A Model Context Protocol (MCP) server for interacting with Li.FI cross-chain bridge and swap aggregator.

Built with FastMCP framework for robust MCP protocol implementation.

📋 Table of Contents

• Quick Start
• Tool Categories
• Testing Without Credentials
• Setting Up Wallet Tools
• Complete Testing Guide
• Usage Examples
• Troubleshooting

🚀 Quick Start

Prerequisites

• Python 3.10 or higher
• uv package manager (install with: curl -LsSf https://astral.sh/uv/install.sh | sh)

Installation

# 1. Navigate to project directory
cd lifi-mcp-python

# 2. Install dependencies
uv sync

# 3. Start Inspector (easiest way to test)
./run-inspector-fast.sh

Browser opens automatically with working MCP server! ✅

🛠️ Tool Categories

✅ Read-Only Tools (NO Credentials Needed)

These 12 tools work immediately without any wallet or credentials:

✨ You can test all of these immediately!

📄 Pagination Support: Tools marked with ✅ support pagination to handle large result sets efficiently.

🔐 Wallet Tools (Credentials REQUIRED)

These 5 tools require an Ethereum wallet keystore:

⚠️ Warning: Wallet tools can spend your cryptocurrency. Always test on testnets first!

📄 Using Pagination

Some tools return large amounts of data. These tools support pagination to make results more manageable:

Paginated Tools

• get_chains - Lists 50+ blockchain chains
• get_tokens - Can list thousands of tokens
• get_connections - Can return hundreds of chain connections
• get_tools_list - Lists all bridges and DEXs

Pagination Parameters

Example: Paginated get_chains

{
  "page": 1,
  "page_size": 10
}

Response:

{
  "chains": [
    { "id": 1, "name": "Ethereum", ... },
    { "id": 10, "name": "Optimism", ... },
    ...10 items total...
  ],
  "pagination": {
    "page": 1,
    "page_size": 10,
    "total_items": 57,
    "total_pages": 6,
    "has_next": true,
    "has_prev": false
  }
}

Example: Get Next Page

{
  "page": 2,
  "page_size": 10
}

Example: Larger Page Size

{
  "page": 1,
  "page_size": 100
}

Pagination Response Fields

🧪 Testing Without Credentials (Read-Only Mode)

Step 1: Start Inspector

cd lifi-mcp-python
./run-inspector-fast.sh

What happens:

• Terminal shows: ✅ Setup verified!
• Browser opens automatically
• Inspector shows: "Server: Connected"
• Tools dropdown shows 12+ tools

Step 2: Test Your First Tool

In the browser Inspector:

1. Select tool: get_chains
2. Arguments: {}
3. Click: "Call Tool"
4. Result: JSON with 57+ blockchain chains ✅

Step 3: More Test Examples

Example 1: Get Ethereum Chain Info

Tool: get_chain_by_name
Arguments: {
  "name": "ethereum"
}

Result:

{
  "id": 1,
  "name": "Ethereum",
  "key": "eth",
  "chainType": "EVM",
  "nativeToken": {
    "symbol": "ETH",
    "decimals": 18,
    "address": "0x0000000000000000000000000000000000000000"
  }
}

Example 2: Check Vitalik's ETH Balance

Tool: get_native_token_balance
Arguments: {
  "rpcUrl": "https://eth.llamarpc.com",
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
}

Result:

{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "balance": "1234.56",
  "symbol": "ETH",
  "decimals": 18
}

Example 3: Get USDC Token Info

Tool: get_token
Arguments: {
  "chain": "1",
  "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
}

Result:

{
  "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "symbol": "USDC",
  "decimals": 6,
  "name": "USD Coin",
  "chainId": 1,
  "logoURI": "https://..."
}

Example 4: Get Swap Quote (No Execution)

Tool: get_quote
Arguments: {
  "fromChain": "1",
  "toChain": "137",
  "fromToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "toToken": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  "fromAddress": "0xYourAddress",
  "fromAmount": "1000000"
}

Result: Complete quote with estimated output, fees, and transaction data (but doesn't execute)

🔐 Setting Up Wallet Tools (Requires Credentials)

What You Need

To use wallet tools, you need an Ethereum keystore file. This is an encrypted JSON file containing your private key.

Option 1: Create a Test Wallet (RECOMMENDED for Testing)

Step 1: Create Keystore with MetaMask

1. Install MetaMask: https://metamask.io/
2. Create new wallet or use existing
3. Export private key:
   • MetaMask → Account Details → Export Private Key
   • Enter password
   • Copy private key (starts with 0x...)

Step 2: Convert to Keystore Format

Use Python to create encrypted keystore:

from eth_account import Account
import json
import getpass

# Your private key from MetaMask
private_key = "0x..." # Paste here

# Create account
account = Account.from_key(private_key)

# Get password for encryption
password = getpass.getpass("Enter password for keystore: ")

# Create keystore
keystore = account.encrypt(password)

# Save to file
keystore_path = f"~/.lifi-mcp/keystore/{account.address}.json"
import os
os.makedirs(os.path.dirname(os.path.expanduser(keystore_path)), exist_ok=True)

with open(os.path.expanduser(keystore_path), 'w') as f:
    json.dump(keystore, f)

print(f"✅ Keystore saved to: {keystore_path}")
print(f"📍 Address: {account.address}")

Step 3: Fund Your Test Wallet

For Testing (Use Testnet!):

1. Get Testnet ETH:

   • Sepolia Faucet: https://sepoliafaucet.com/
   • Paste your address
   • Receive free test ETH

2. Get Testnet Tokens:

   • Bridge testnet ETH to other chains
   • Use testnet DEXs to get tokens

⚠️ NEVER USE MAINNET FOR TESTING! Always start with testnets.

Option 2: Use Existing Keystore

If you already have a keystore file (e.g., from Geth, MyEtherWallet):

1. Copy keystore to standard location:

   mkdir -p ~/.lifi-mcp/keystore
   cp your-keystore.json ~/.lifi-mcp/keystore/
   

2. Note the filename (e.g., UTC--2024-...--0xabcd1234)

Option 3: Hardware Wallet (Advanced)

Hardware wallets (Ledger, Trezor) are more secure but require additional setup. See for instructions.

🔑 Using Wallet Tools

Method 1: Start Inspector with Keystore

cd lifi-mcp-python

# Replace with your keystore filename and password
npx @modelcontextprotocol/inspector \
  "$(pwd)/.venv/bin/python" \
  -m lifi_mcp_python.main_fastmcp \
  --keystore "UTC--2024-...--0xabcd1234.json" \
  --password "YourPassword"

What happens:

• Server loads your wallet
• All 17 tools are now available (12 read-only + 5 wallet)
• Your address is loaded and ready

Method 2: Run Server Directly

cd lifi-mcp-python

# Start server with wallet
.venv/bin/python -m lifi_mcp_python.main_fastmcp \
  --keystore "UTC--2024-...--0xabcd1234.json" \
  --password "YourPassword"

Keystore Location

The server looks for keystores in:

~/.lifi-mcp/keystore/

Or you can provide the full path:

--keystore "/full/path/to/keystore.json"

🧪 Complete Testing Guide

Phase 1: Read-Only Testing (5 minutes)

No credentials needed!

# 1. Start Inspector
./run-inspector-fast.sh

# 2. Test these tools in order:

1. get_chains → {}
2. get_chain_by_name → {"name": "ethereum"}
3. get_tokens → {"chains": "1"}
4. get_native_token_balance → {"rpcUrl": "https://eth.llamarpc.com", "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"}

Phase 2: Quote Testing (10 minutes)

Still no credentials needed!

# Get a quote for swapping USDC on Ethereum to USDC on Polygon

Tool: get_quote
Arguments: {
  "fromChain": "1",
  "toChain": "137",
  "fromToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "toToken": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  "fromAddress": "0xYourAddress",
  "fromAmount": "1000000"
}

What you get:

• Estimated output amount
• Gas fees
• Route (which bridges/DEXs used)
• Transaction data (for execution)

Phase 3: Wallet Testing (WITH Credentials)

⚠️ Use Testnet Only!

# 1. Create test wallet (see above)
# 2. Fund with testnet ETH
# 3. Start Inspector with keystore

npx @modelcontextprotocol/inspector \
  "$(pwd)/.venv/bin/python" \
  -m lifi_mcp_python.main_fastmcp \
  --keystore "your-keystore.json" \
  --password "YourPassword"

Test wallet tools:

1. get_wallet_address → {}

   • Should show your address

2. get_native_token_balance → {"rpcUrl": "https://rpc.sepolia.org", "address": "YOUR_ADDRESS"}

   • Check your testnet balance

3. approve_token (if needed) → See examples below

4. transfer_token → See examples below

Phase 4: Execute Swap (ADVANCED - Testnet Only)

# Step 1: Get quote
Tool: get_quote
Arguments: {...} # See Phase 2

# Step 2: From quote response, copy the "transactionRequest" object

# Step 3: Execute
Tool: execute_quote
Arguments: {
  "rpcUrl": "https://rpc.sepolia.org",
  "transactionRequest": {...} # Paste from quote
}

📖 Usage Examples

Example 1: Check Token Balance

No credentials needed!

Tool: get_token_balance
Arguments: {
  "rpcUrl": "https://eth.llamarpc.com",
  "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "walletAddress": "0xYourAddress"
}

Example 2: Check Token Allowance

No credentials needed!

Tool: get_allowance
Arguments: {
  "rpcUrl": "https://eth.llamarpc.com",
  "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "ownerAddress": "0xYourAddress",
  "spenderAddress": "0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE"
}

Example 3: Approve Token (Requires Keystore)

Tool: approve_token
Arguments: {
  "rpcUrl": "https://rpc.sepolia.org",
  "tokenAddress": "0xTokenAddress",
  "spenderAddress": "0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE",
  "amount": "1000000"
}

Example 4: Transfer Tokens (Requires Keystore)

Tool: transfer_token
Arguments: {
  "rpcUrl": "https://rpc.sepolia.org",
  "tokenAddress": "0xTokenAddress",
  "to": "0xRecipientAddress",
  "amount": "1000000"
}

Example 5: Transfer Native Token (Requires Keystore)

Tool: transfer_native
Arguments: {
  "rpcUrl": "https://rpc.sepolia.org",
  "to": "0xRecipientAddress",
  "amount": "1000000000000000"
}

🔍 Finding RPC URLs

Free Public RPCs

Dedicated RPC Services (Better Performance)

1. Infura: https://infura.io/

   • Free tier: 100K requests/day
   • Sign up → Create project → Copy endpoint

2. Alchemy: https://www.alchemy.com/

   • Free tier: 300M compute units/month
   • Sign up → Create app → Copy HTTPS endpoint

3. Ankr: https://www.ankr.com/

   • Free tier available
   • No signup needed for public endpoints

🧰 Use in Claude Desktop

Configuration

Add to claude_desktop_config.json:

Read-Only Mode (No Wallet):

{
  "mcpServers": {
    "lifi": {
      "command": "/Users/jayeshkumarchowdary/Downloads/lifi-mcp-main/lifi-mcp-python/.venv/bin/python",
      "args": ["-m", "lifi_mcp_python.main_fastmcp"]
    }
  }
}

With Wallet (Testnet Only!):

{
  "mcpServers": {
    "lifi": {
      "command": "/Users/jayeshkumarchowdary/Downloads/lifi-mcp-main/lifi-mcp-python/.venv/bin/python",
      "args": [
        "-m",
        "lifi_mcp_python.main_fastmcp",
        "--keystore",
        "your-keystore.json",
        "--password",
        "YourPassword"
      ]
    }
  }
}

⚠️ Security Note: Storing passwords in config files is NOT secure. Use environment variables or prompt-based authentication for production.

🐛 Troubleshooting

"Module not found"

cd lifi-mcp-python
uv sync

"No tools showing in Inspector"

1. Refresh browser (F5)
2. Wait 5 seconds
3. Check terminal for errors
4. Try: ./run-inspector-fast.sh again

"Keystore not found"

# Check keystore location
ls -la ~/.lifi-mcp/keystore/

# Or provide full path
--keystore "/full/path/to/keystore.json"

"Insufficient funds"

• Check you have enough ETH for gas
• Check token balance: Use get_token_balance tool
• For testnets: Get more from faucets

"Transaction failed"

• Check gas price (might be too low)
• Check token allowance: Use get_allowance tool
• Check RPC URL is correct
• Try different RPC endpoint

📚 Additional Resources

• Li.FI API Documentation: https://docs.li.fi/
• Li.FI Supported Chains: https://li.fi/chains
• Model Context Protocol: https://modelcontextprotocol.io/
• FastMCP Framework: https://github.com/jlowin/fastmcp
• Ethereum Testnet Faucets: https://faucetlink.to/

🔒 Security Best Practices

DO ✅

• Test on testnets first
• Use dedicated test wallets
• Keep keystores secure
• Never share private keys
• Verify transaction details
• Use hardware wallets for large amounts

DON'T ❌

• Use mainnet for testing
• Store passwords in plaintext
• Commit keystores to git
• Share keystores with anyone
• Skip transaction verification
• Use production wallets for testing

📋 Configuration Files

This project includes two configuration files for MCP client integration:

lifi_mcp_config.json

MCP client configuration for launching and connecting to the server. Use this with MCP clients like Claude Desktop or Inspector.

{
  "mcpServers": {
    "lifi-mcp": {
      "command": "bash",
      "args": ["-c", "cd /path/to/lifi-mcp-python && .venv/bin/python -m lifi_mcp_python.main_fastmcp"],
      "type": "stdio"
    }
  }
}

lifi_mcp_metadata.json

Comprehensive metadata describing:

• All 17 tools with detailed parameters
• Supported blockchain networks (50+)
• Security model and best practices
• Installation and usage information
• API provider details

See for detailed documentation about these configuration files.

📖 Additional Resources

• Li.FI Documentation - Official Li.FI API docs
• MCP Documentation - Model Context Protocol specs
• FastMCP Documentation - FastMCP framework docs

📝 License

MIT License - See file for details.

🙋 Getting Help

• Quick Reference: See for a one-page guide
• Configuration Files: See for integration details
• Issues or Questions: Refer to the troubleshooting section above
• Bugs or Feature Requests: Open an issue on GitHub

🎉 Ready to start? Run ./run-inspector-fast.sh now!