READMEmain

🔄 Odos MCP Server

📖 Overview

The Odos MCP Server enables AI agents to interact with Odos, a leading DEX aggregator that finds optimal swap routes across multiple decentralized exchanges. This server provides comprehensive access to quote retrieval and swap execution functionality.

By implementing the Model Context Protocol (MCP), this server allows Large Language Models (LLMs) to fetch swap quotes, compare prices, and execute token swaps directly through their context window, bridging the gap between AI and decentralized finance.

✨ Features

Quote Retrieval: Get optimal swap quotes with best routes across multiple DEXs.
Multi-Chain Support: Execute swaps on various blockchain networks including Fraxtal, Ethereum, and more.
Swap Execution: Execute token swaps with automatic allowance handling.
Chain ID Lookup: Retrieve chain IDs for supported blockchain networks.

📦 Installation

🚀 Using npx (Recommended)

To use this server without installing it globally:

npx @iqai/mcp-odos

🔧 Build from Source

git clone https://github.com/IQAIcom/mcp-odos.git
cd mcp-odos
pnpm install
pnpm run build

⚡ Running with an MCP Client

Add the following configuration to your MCP client settings (e.g., claude_desktop_config.json).

📋 Minimal Configuration

{
  "mcpServers": {
    "odos": {
      "command": "npx",
      "args": ["-y", "@iqai/mcp-odos"],
      "env": {
        "WALLET_PRIVATE_KEY": "your_wallet_private_key_here"
      }
    }
  }
}

⚙️ Advanced Configuration (Local Build)

{
  "mcpServers": {
    "odos": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-odos/dist/index.js"],
      "env": {
        "WALLET_PRIVATE_KEY": "your_wallet_private_key_here"
      }
    }
  }
}

🔐 Configuration (Environment Variables)

Variable	Required	Description	Default
`WALLET_PRIVATE_KEY`	Yes	Your wallet private key for executing swaps	-

💡 Usage Examples

🔍 Getting Quotes

"Get a quote to swap 1000 USDC for FRAX on Fraxtal."
"What's the best rate to swap ETH for USDC?"
"How much FRAX will I get for 100 USDC on Fraxtal?"

💱 Executing Swaps

"Swap 100 USDC for FRAX on Fraxtal."
"Execute a trade: sell 1000 USDC for ETH."
"Trade my USDC for the maximum amount of FRAX."

🔗 Chain Information

"What is the chain ID for Fraxtal?"
"Get the chain ID for Ethereum mainnet."

🛠️ MCP Tools

`ODOS_GET_CHAIN_ID`

Get the chain ID for a given chain name

Parameter	Type	Required	Description
`chain`	string	✅	The chain name to get the ID for

`ODOS_GET_QUOTE`

Get a quote for a swap or exchange operation

Parameter	Type	Required	Default	Description
`chain`	string		"fraxtal"	The blockchain network to execute the transaction on. uses fraxtal as default
`fromToken`	string	✅		The token to swap from (address).
`toToken`	string	✅		The token to swap to (address).
`amount`	string	✅		The amount of tokens to swap, in wei.
`prettyFormat`	boolean		true	Whether to pretty format the quote.

`ODOS_SWAP`

Execute a swap transaction

Parameter	Type	Required	Default	Description
`chain`	string		"fraxtal"	The blockchain network to execute the transaction on. uses fraxtal as default
`fromToken`	string	✅		The token to swap from (address).
`toToken`	string	✅		The token to swap to (address).
`amount`	string	✅		The amount of tokens to swap, in wei.
`prettyFormat`	boolean		true	Whether to pretty format the quote.

👨‍💻 Development

🏗️ Build Project

pnpm run build

👁️ Development Mode (Watch)

pnpm run watch

✅ Linting & Formatting

pnpm run lint
pnpm run format

📁 Project Structure

src/tools/: Individual tool definitions
src/services/: API client and business logic
src/utils/: Shared utilities
src/index.ts: Server entry point

📚 Resources

⚠️ Disclaimer

This project is an unofficial tool and is not directly affiliated with Odos. It interacts with financial data and decentralized exchanges. Users should exercise caution and verify all data independently. Trading on decentralized exchanges involves risk.

📄 License

ISC

mcp-odos