DEX MCP RS - Ethereum DeFi MCP Server

A Model Context Protocol (MCP) server built in Rust that enables AI agents to query balances and execute token swaps on Ethereum. This server provides three core tools for interacting with Ethereum and Uniswap V2.

Features

• get_balance - Query ETH and ERC20 token balances for any address
• get_token_price - Get real-time token prices in ETH and USD from Uniswap V2 pools
• swap_tokens - Simulate token swaps on Uniswap V2 (does not execute on-chain)

Prerequisites

• Rust 1.70 or later
• Ethereum RPC endpoint (Infura, Alchemy, or local node)
• Private key for transaction signing (required for gas estimation)

Setup Instructions

1. Clone the Repository

git clone https://github.com/yourusername/dex-mcp-rs.git
cd dex-mcp-rs

2. Configure Environment Variables

Create a .env file in the project root:

cp .env.example .env

Edit .env and add your credentials:

RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY
PRIVATE_KEY=your_private_key_here

⚠️ Security Warning: Never commit your .env file or share your private key!

3. Build the Project

cargo build --release

4. Run the Server

cargo run --release

The server will start and listen for MCP requests on stdin/stdout.

Design Decisions

Why Alloy? Alloy is a modern, high-performance Ethereum library for Rust with excellent type safety and modular design. It provides better ergonomics and maintenance than the older ethers-rs library.

Why Uniswap V2? V2 has a simpler constant product formula (x * y = k) compared to V3's concentrated liquidity model, making it easier to implement and understand while still providing accurate pricing for most token pairs.

Why on-chain pricing? Deriving prices directly from Uniswap pool reserves eliminates external API dependencies and ensures data is always current and trustless, though it requires more RPC calls.

Why eth_call for simulation? Using eth_call allows us to simulate transactions without executing them on-chain, providing accurate gas estimates and catching potential failures without spending gas or requiring token approvals.

Testing

Run the test suite:

cargo test

Note: Integration tests are marked with #[ignore] by default as they require a valid RPC connection. To run them:

cargo test -- --ignored

Make sure your .env file is configured before running integration tests.

Known Limitations

• Mainnet only: Currently configured for Ethereum mainnet. To use testnets, update the RPC URL and contract addresses.
• Uniswap V2 only: Does not support Uniswap V3 or other DEXes.
• Requires funded wallet: Gas estimation requires a wallet with some ETH balance.
• Price accuracy: Assumes sufficient liquidity in WETH and USDC pairs. Low liquidity pairs may have inaccurate pricing.
• No transaction execution: The swap tool only simulates; it does not execute real swaps.

Architecture

src/
├── main.rs              # MCP server setup and request routing
├── config.rs            # Configuration management
├── types.rs             # Shared types and request/response structures
├── ethereum/
│   ├── mod.rs           # Ethereum client wrapper
│   └── contracts.rs     # Smart contract ABIs (ERC20, Uniswap V2)
└── tools/
    ├── mod.rs           # Tool module exports
    ├── balance.rs       # get_balance implementation
    ├── price.rs         # get_token_price implementation
    └── swap.rs          # swap_tokens implementation

Smart Contract Addresses (Mainnet)

• Uniswap V2 Router: 0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D
• Uniswap V2 Factory: 0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f
• WETH: 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
• USDC: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48

Development

Project Structure

The project follows a modular architecture:

• config: Environment and configuration management
• ethereum: Blockchain interaction layer with alloy
• tools: MCP tool implementations (balance, price, swap)
• types: Shared data structures

Adding New Tools

1. Define input/output types in src/types.rs
2. Implement the tool logic in src/tools/
3. Register the tool in src/main.rs in the create_router function
4. Add tests in tests/integration_tests.rs

Contributing

Contributions are welcome! Please ensure:

• Code compiles without warnings: cargo build
• All tests pass: cargo test
• Code is formatted: cargo fmt
• Code passes clippy: cargo clippy

License

MIT

Security

This is demonstration code for educational purposes. For production use:

• Use a secure key management system (HSM, KMS)
• Implement rate limiting
• Add comprehensive error handling
• Audit all code thoroughly
• Never expose private keys in logs or errors

Acknowledgments

Built with:

• Alloy - Ethereum library
• MCP-RS - Model Context Protocol SDK
• Tokio - Async runtime
• Uniswap V2 - Decentralized exchange protocol