io.github.matiosera3-ops/defi-mcp

defi-mcp

An MCP (Model Context Protocol) server that gives AI agents direct, on-chain access to DeFi data on EVM chains — wallet balances, Aave v3 lending positions, and live token prices, with no centralized API in the middle.

Status: Live and functional. 5 tools available today, more on the roadmap.

Why

Most "DeFi + AI" integrations route through a centralized API that can rate-limit, paywall, or simply disappear. defi-mcp talks directly to the chain (via your own RPC provider) and to first-party oracles (Chainlink), so the data your AI agent gets is exactly what's on-chain — verifiable, and not dependent on a third-party API staying online.

Tools

get_token_balance

Reads the ERC-20 balance of any wallet address for a supported token.

Supported tokens:

• Polygon: USDC, USDC.e, USDT, WETH, WMATIC, WBTC, DAI, AAVE
• Arbitrum: USDC, USDC.e (bridged), USDT, WETH, WBTC, ARB

// get_token_balance(address="0x...", token_symbol="USDC", chain="polygon")
{
  "address": "0x...",
  "token": "USDC",
  "chain": "polygon",
  "balance": 268.21,
  "raw_balance": "268210000",
  "decimals": 6
}

get_aave_position

Reads a user's full Aave v3 lending/borrowing position: collateral, debt, available borrowing power, and health factor — straight from the Aave v3 Pool contract.

// get_aave_position(address="0x...", chain="polygon")
{
  "address": "0x...",
  "chain": "polygon",
  "total_collateral_usd": 969.78,
  "total_debt_usd": 288.16,
  "available_borrows_usd": 484.86,
  "liquidation_threshold_pct": 82.79,
  "ltv_pct": 79.71,
  "health_factor": 2.79,
  "has_active_position": true
}

A health_factor below 1.0 means the position is at risk of liquidation. A null health factor means the user has no outstanding debt.

get_token_price

Reads the current USD price of a token directly from a Chainlink price feed — the same oracle DeFi protocols use internally, so the price is consistent with what get_aave_position reports.

Supported feeds:

• Polygon: ETH/WETH, MATIC/WMATIC, WBTC, USDC, USDT
• Arbitrum: ETH/WETH, WBTC, ARB, USDC, USDT

// get_token_price(token_symbol="WBTC", chain="polygon")
{
  "token": "WBTC",
  "chain": "polygon",
  "price_usd": 63835.77,
  "decimals": 8,
  "updated_at": 1782032816
}

simulate_swap

Simulates a Uniswap v3 swap on-chain via the QuoterV2 contract — no transaction submitted, no wallet needed. Tries all four fee tiers (0.01%, 0.05%, 0.3%, 1%) and returns the best available output amount.

Supported tokens:

• Polygon: USDC, USDC.e, USDT, WETH, WMATIC, WBTC, DAI, AAVE
• Arbitrum: USDC, USDC.e (bridged), USDT, WETH, WBTC, ARB

// simulate_swap(token_in="WMATIC", token_out="USDC", amount_in=100.0, chain="polygon")
{
  "chain": "polygon",
  "token_in": "WMATIC",
  "token_out": "USDC",
  "amount_in": 100.0,
  "amount_out": 7.990547,
  "fee_tier_used_pct": 0.05,
  "fee_tier_used_bps": 500,
  "gas_estimate": 122770
}

If no pool exists for the pair at any fee tier, returns {"error": "No liquidity found for this pair on any fee tier"}.

hello

Simple connectivity check — confirms the MCP server is reachable and responding.

Supported chains

Installation

Requires Python 3.10+ and an RPC provider API key (e.g. Alchemy, free tier works).

pip install defi-mcp

Create a .env file in your working directory (see .env.example):

POLYGON_RPC_URL=https://polygon-mainnet.g.alchemy.com/v2/YOUR_API_KEY
ARBITRUM_RPC_URL=https://arb-mainnet.g.alchemy.com/v2/YOUR_API_KEY

Each chain only needs its RPC URL configured. Tools called with chain="arbitrum" will fail gracefully if ARBITRUM_RPC_URL is not set.

Usage with Claude Desktop

Add this to your Claude Desktop MCP config (claude_desktop_config.json):

{
  "mcpServers": {
    "defi-mcp": {
      "command": "uvx",
      "args": ["defi-mcp"],
      "env": {
        "POLYGON_RPC_URL": "https://polygon-mainnet.g.alchemy.com/v2/YOUR_API_KEY",
        "ARBITRUM_RPC_URL": "https://arb-mainnet.g.alchemy.com/v2/YOUR_API_KEY"
      }
    }
  }
}

Restart Claude Desktop, and the tools above will be available to the model.

Testing locally

You can test the server directly with the official MCP Inspector:

npx @modelcontextprotocol/inspector uvx defi-mcp

Roadmap

• [ ] Track Uniswap v3 LP positions and impermanent loss
• [ ] Monitor protocol TVLs
• [ ] Additional chains (Ethereum, Base)
• [ ] defi-mcp-cloud — hosted tier with MEV-specific tools, caching, and higher rate limits

Architecture

Open-core model: this repository (MIT licensed) covers standard on-chain read tools. A separate defi-mcp-cloud will offer a hosted version with MEV-related tools, request caching, and managed RPC access for users who don't want to run their own infrastructure.

Resources

• defi-storage-cheatsheet — verified EVM storage slot layouts for Aave v3 and Uniswap v3, with web3.py snippets. Useful if you want to read on-chain state directly via eth_getStorageAt instead of calling view functions — the lower-level approach behind some of what this server does under the hood.

Contributing

Issues and PRs welcome. This is an early-stage project — feedback on what tools would actually be useful to you is especially valuable.

License

MIT