Skip to main content
Glama

Paloma DEX MCP Server

A Model Context Protocol (MCP) server that enables AI agents to interact with Paloma DEX across 7 EVM chains. Built with FastMCP framework for modern MCP implementations.

Overview

This MCP server provides AI agents with tools to access blockchain data and prepare for decentralized trading operations on Paloma DEX. The server supports cross-chain functionality across Ethereum, Arbitrum, Optimism, Base, BSC, Polygon, and Gnosis chains.

Related MCP server: EVM MCP Server

Features

Available Tools

Blockchain Data Access

  • get_account_info: Get account address and native token balances across all chains

  • get_pusd_balance: Get PUSD token balance on a specific chain

  • get_chain_info: Get detailed information about a specific blockchain

  • list_supported_chains: List all supported chains with their configurations

  • get_address_balances: Get balances for any Ethereum address across all chains

ETF Trading Tools

  • get_etf_tokens: Get available ETF tokens on a specific chain

  • get_etf_price: Get buy and sell prices for an ETF token (by EVM address)

  • get_etf_price_by_symbol: Get ETF price by token symbol (recommended)

  • get_etf_price_by_paloma_denom: Get ETF price by Paloma denomination

  • get_etf_balance: Get ETF token balance for a wallet address

  • buy_etf_token: Buy ETF tokens using input tokens (simulation)

  • sell_etf_token: Sell ETF tokens back to base currency (simulation)

Chain Support

Supports all 7 EVM chains used by Paloma DEX:

  • Ethereum Mainnet (Chain ID: 1)

  • Arbitrum One (Chain ID: 42161)

  • Optimism (Chain ID: 10)

  • Base (Chain ID: 8453)

  • BNB Smart Chain (Chain ID: 56)

  • Polygon (Chain ID: 137)

  • Gnosis (Chain ID: 100)

Key Capabilities

  • Multi-Chain Data Access: Query balances and chain information across all 7 supported chains

  • ETF Trading Support: Complete ETF token ecosystem integration with Paloma DEX API

  • FastMCP Framework: Built with modern MCP implementation for better performance

  • Web3 Integration: Direct blockchain interaction via Web3 clients

  • Transaction Simulation: Safe simulation of trading operations before execution

  • Error Handling: Comprehensive error management and validation

  • Address Validation: Ethereum address format validation

  • Contract Integration: Integration with PUSD and ETF connector contracts

Installation

  1. Clone the repository:

    git clone https://github.com/Cieloc/mcpPADEX.git
    cd mcpPADEX
  2. Install dependencies using uv:

    uv sync

Configuration

  1. Set up environment variables:

    cp .env.example .env
  2. Configure your .env file with the following required variables:

    # REQUIRED: Your private key for transaction signing
    # WARNING: Keep this secure and never commit to version control
    PRIVATE_KEY=your_private_key_here
    
    # Contract addresses for each chain (obtain from Paloma DEX)
    PUSD_TOKEN_ETH=
    PUSD_CONNECTOR_ETH=
    ETF_CONNECTOR_ETH=
    # ... (repeat for all chains)
    
    # Optional: Moralis API key for enhanced features
    MORALIS_SERVICE_API_KEY=your_moralis_api_key_here
  3. Obtain contract addresses from Paloma DEX documentation or team for:

    • PUSD token addresses

    • PUSD connector addresses

    • ETF connector addresses

Usage

Running the Server

uv run padex.py

The server will start and listen for MCP protocol messages via stdin/stdout.

Tool Examples

Get Account Information

{
  "tool": "get_account_info",
  "arguments": {}
}

Get PUSD Balance

{
  "tool": "get_pusd_balance",
  "arguments": {
    "chain_id": "1"
  }
}

Get Chain Information

{
  "tool": "get_chain_info",
  "arguments": {
    "chain_id": "42161"
  }
}

List All Supported Chains

{
  "tool": "list_supported_chains",
  "arguments": {}
}

Get Address Balances

{
  "tool": "get_address_balances",
  "arguments": {
    "address": "0x742d35Cc6648C4532b6C4EC000e40fd94aea4966"
  }
}

Get Available ETF Tokens

{
  "tool": "get_etf_tokens",
  "arguments": {
    "chain_id": "1"
  }
}

Get ETF Token Price (by EVM address)

{
  "tool": "get_etf_price",
  "arguments": {
    "chain_id": "1",
    "etf_token_address": "0x1234567890123456789012345678901234567890"
  }
}
{
  "tool": "get_etf_price_by_symbol",
  "arguments": {
    "symbol": "PAGOLD"
  }
}

Get ETF Price by Paloma Denomination

{
  "tool": "get_etf_price_by_paloma_denom",
  "arguments": {
    "paloma_denom": "factory/paloma18xrvj2ffxygkmtqwf3tr6fjqk3w0dgg7m6ucwx/palomagold"
  }
}

Get ETF Token Balance

{
  "tool": "get_etf_balance",
  "arguments": {
    "chain_id": "1",
    "etf_token_address": "0x1234567890123456789012345678901234567890",
    "wallet_address": "0x742d35Cc6648C4532b6C4EC000e40fd94aea4966"
  }
}

Buy ETF Tokens (Simulation)

{
  "tool": "buy_etf_token",
  "arguments": {
    "chain_id": "1",
    "etf_token_address": "0x1234567890123456789012345678901234567890",
    "input_token_address": "native",
    "input_amount": "1.0",
    "slippage": 2.0
  }
}

Sell ETF Tokens (Simulation)

{
  "tool": "sell_etf_token",
  "arguments": {
    "chain_id": "1",
    "etf_token_address": "0x1234567890123456789012345678901234567890",
    "etf_amount": "10.0"
  }
}

Architecture

Core Components

  • padex.py: Main MCP server implementation using FastMCP framework

  • main.py: Simple entry point (Hello World)

  • FastMCP Framework: Modern MCP server implementation with lifecycle management

  • Chain Configuration: Complete configuration for all 7 supported chains

  • Web3 Clients: Individual Web3 connections for each blockchain

Architecture Pattern

The server uses FastMCP's lifespan context management:

@asynccontextmanager
async def paloma_dex_lifespan(server: FastMCP) -> AsyncIterator[PalomaDEXContext]:
    # Initialize Web3 clients and resources
    yield context
    # Cleanup resources

Security Considerations

⚠️ Important Security Notes:

  • Private keys are stored in environment variables

  • Ensure your .env file is never committed to version control

  • The .gitignore file excludes .env by default

  • Consider using more secure key management for production use

Dependencies

  • mcp[cli]: Model Context Protocol with FastMCP framework

  • web3: Ethereum blockchain interaction

  • eth-account: Private key and transaction signing

  • eth-abi: ABI encoding for contract calls

  • httpx: HTTP client for API interactions

  • python-dotenv: Environment variable management

API Integrations

The server integrates with:

  • Blockchain RPC Endpoints: Direct connection to each supported chain

  • ERC-20 Token Contracts: For PUSD and ETF token balance queries

  • Paloma DEX API: Live integration for ETF token data and pricing

  • ETF Connector Contracts: Smart contracts for ETF trading operations

Development

Project Structure

mcpPADEX/
├── padex.py                      # Main FastMCP server implementation
├── padex_old.py                  # Previous implementation (backup)
├── main.py                       # Simple entry point
├── pyproject.toml                # Project dependencies
├── .env                          # Environment variables (not committed)
├── .gitignore                    # Git ignore rules
├── MCP_DOCUMENTATION.md          # MCP protocol reference
├── MCP_PYTHON_SDK_REFERENCE.md   # FastMCP SDK reference
├── mcp-llms-full-reference.txt   # Complete MCP reference
└── README.md                     # This file

Adding New Features

The server uses FastMCP decorators for easy extension:

@mcp.tool()
async def new_tool(ctx: Context, param: str) -> str:
    """Tool description"""
    # Implementation
    return result

@mcp.resource("resource://pattern/{id}")
async def new_resource(id: str) -> str:
    """Resource description"""
    # Implementation
    return data

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is open source. Please check the license file for details.

Disclaimer

This software is provided "as is" without warranty. Trading cryptocurrencies involves risk of loss. Use at your own risk and ensure you understand the implications of automated trading before deployment.

Support

For questions about Paloma DEX integration, consult the Paloma DEX documentation or reach out to the Paloma team.

For MCP-related questions, see the Model Context Protocol documentation.

Available Tools

21 tools
add_liquidityB

Add liquidity to a trading pool using the Trader contract.

Args:
    chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
    token0_address: Address of first token
    token1_address: Address of second token
    token0_amount: Amount of first token in wei
    token1_amount: Amount of second token in wei

Returns:
    JSON string with liquidity addition transaction details.

Inputs: chain_id (required), token0_address (required), token1_address (required), token0_amount (required), +1 more.

approve_token_spendingA

Approve token spending for trading (two-step approval process).

Args:
    chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
    token_address: Address of token to approve
    spender_address: Address that will spend the tokens (typically Trader contract)
    amount: Amount to approve in wei (defaults to unlimited)

Returns:
    JSON string with approval transaction details.

Inputs: chain_id (required), token_address (required), spender_address (required), amount.

buy_etf_tokenA

Buy ETF tokens using input tokens (simulation only - no actual transaction).

Args:
    chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
    etf_token_address: Address of the ETF token to buy
    input_token_address: Address of token to spend (use 'native' for ETH/BNB/MATIC/xDAI)
    input_amount: Amount of input token to spend (in token units, e.g. '1.5')
    slippage: Slippage tolerance as percentage (default: 2.0)

Returns:
    JSON string with transaction simulation details.

Inputs: chain_id (required), etf_token_address (required), input_token_address (required), input_amount (required), +1 more.

check_token_allowanceA

Check token allowance for a specific owner and spender.

Args:
    chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
    token_address: Address of the token
    owner_address: Address of the token owner
    spender_address: Address of the spender (typically Trader contract)

Returns:
    JSON string with allowance information.

Inputs: chain_id (required), token_address (required), owner_address (required), spender_address (required).

execute_token_swapB

Execute a token swap using the Trader contract.

Args:
    chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
    from_token_address: Address of token to swap from
    to_token_address: Address of token to swap to
    amount_wei: Amount to swap in wei format

Returns:
    JSON string with swap transaction details.

Inputs: chain_id (required), from_token_address (required), to_token_address (required), amount_wei (required).

get_account_infoB

Get account information including address and balances across all chains.

Returns:
    JSON string with account address and native token balances on all supported chains.

Inputs: no named parameters.

get_address_balancesA

Get balances for a specific address across all chains (concurrent execution).

Args:
    address: Ethereum address to check balances for
    timeout_seconds: Timeout for the entire operation (default: 30 seconds)

Returns:
    JSON string with balance information across all chains.

Inputs: address (required), timeout_seconds.

get_address_balance_single_chainA

Get balance for a specific address on a single chain (faster).

Args:
    address: Ethereum address to check balances for
    chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)

Returns:
    JSON string with balance information for the specified chain.

Inputs: address (required), chain_id (required).

get_available_trading_tokensB

Get available tokens for trading on a specific chain.

Args:
    chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)

Returns:
    JSON string with available trading tokens and their information.

Inputs: chain_id (required).

get_chain_infoB

Get detailed information about a specific chain.

Args:
    chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)

Returns:
    JSON string with chain configuration and status.

Inputs: chain_id (required).

get_etf_balanceB

Get ETF token balance for a wallet address.

Args:
    chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
    etf_token_address: Address of the ETF token
    wallet_address: Wallet address to check (defaults to server wallet)

Returns:
    JSON string with ETF token balance information.

Inputs: chain_id (required), etf_token_address (required), wallet_address.

get_etf_priceB

Get buy and sell prices for an ETF token.

Args:
    chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
    etf_token_address: Address of the ETF token

Returns:
    JSON string with buy and sell prices for the ETF token.

Inputs: chain_id (required), etf_token_address (required).

get_etf_price_by_paloma_denomB

Get ETF price by Paloma denomination.

Args:
    paloma_denom: Paloma denomination (e.g., factory/paloma18xrvj2ffxygkmtqwf3tr6fjqk3w0dgg7m6ucwx/palomagold)

Returns:
    JSON string with ETF price data.

Inputs: paloma_denom (required).

get_etf_price_by_symbolA

Get ETF price by token symbol from Paloma DEX.

Args:
    symbol: ETF token symbol (e.g., PAGOLD, PABTC2X, PACBOA)

Returns:
    JSON string with ETF price data.

Inputs: symbol (required).

get_etf_tokensB

Get available ETF tokens on a specific chain.

Args:
    chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)

Returns:
    JSON string with available ETF tokens and their information.

Inputs: chain_id (required).

get_pusd_balanceB

Get PUSD token balance on specified chain.

Args:
    chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)

Returns:
    JSON string with PUSD balance information.

Inputs: chain_id (required).

get_token_price_estimateA

Get real-time price estimate for token swap.

Args:
    chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
    input_token_address: Address of token to trade from
    output_token_address: Address of token to trade to
    input_amount: Amount of input token in wei format

Returns:
    JSON string with price estimate and trading information.

Inputs: chain_id (required), input_token_address (required), output_token_address (required), input_amount (required).

list_supported_chainsB

List all supported chains with their configurations.

Returns:
    JSON string with all supported chain information.

Inputs: no named parameters.

remove_liquidityB

Remove liquidity from a trading pool using the Trader contract.

Args:
    chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
    token0_address: Address of first token
    token1_address: Address of second token
    liquidity_amount: Amount of liquidity tokens to remove in wei

Returns:
    JSON string with liquidity removal transaction details.

Inputs: chain_id (required), token0_address (required), token1_address (required), liquidity_amount (required).

sell_etf_tokenA

Sell ETF tokens back to base currency (simulation only - no actual transaction).

Args:
    chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
    etf_token_address: Address of the ETF token to sell
    etf_amount: Amount of ETF tokens to sell (in token units, e.g. '10.5')

Returns:
    JSON string with transaction simulation details.

Inputs: chain_id (required), etf_token_address (required), etf_amount (required).

validate_trade_quoteA

Validate a trade against max spread and liquidity requirements.

Args:
    chain_id: Chain ID (1, 10, 56, 100, 137, 8453, 42161)
    input_token_address: Address of token to trade from
    output_token_address: Address of token to trade to  
    input_amount: Amount of input token in wei format

Returns:
    JSON string with trade validation results.

Inputs: chain_id (required), input_token_address (required), output_token_address (required), input_amount (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 21 tools

    Disambiguation4/5

    Most tools have distinct purposes with clear boundaries, such as add_liquidity vs. remove_liquidity or execute_token_swap vs. validate_trade_quote. However, some overlap exists in ETF price retrieval tools (get_etf_price, get_etf_price_by_paloma_denom, get_etf_price_by_symbol), which could cause confusion despite their different input parameters.

    Naming Consistency5/5

    All tools follow a consistent verb_noun naming pattern using snake_case, such as add_liquidity, check_token_allowance, and get_account_info. The naming is predictable and readable throughout the set, with no deviations in style or convention.

    Tool Count3/5

    With 21 tools, the count is borderline high for a DEX server, potentially overwhelming for agents. While the tools cover various aspects like liquidity, trading, balances, and ETFs, some consolidation might improve usability without losing functionality.

    Completeness5/5

    The tool set provides comprehensive coverage for a DEX domain, including liquidity management (add/remove), trading (swap, validate, price estimates), account/balance queries, ETF operations (buy/sell/price/balance), and chain/token information. No obvious gaps are present, supporting full workflows from approval to execution.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server enabling AI agents to interact with the Solana blockchain for DeFi operations like checking balances, transferring tokens, executing swaps, and fetching price data.
      21
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that enables AI agents to interact with 30+ Ethereum-compatible blockchain networks, providing services like token transfers, contract interactions, and ENS resolution through a unified interface.
      28
      96 npm
      380
      MIT
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Comprehensive Model Context Protocol server that enables AI agents to interact with 30+ Ethereum-compatible blockchain networks, supporting token transfers, smart contract interactions, and ENS name resolution through a unified interface.
      1
      -
    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that enables AI assistants and applications to interact with decentralized exchanges (DEXs), allowing users to get quotes for token swaps and execute swap transactions.
      3
      13 npm
      1
      MIT