{
  "markdown": "# defi-mcp\n\nAn 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.\n\n**Status:** Live and functional. 5 tools available today, more on the roadmap.\n\n## Why\n\nMost \"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.\n\n## Tools\n\n### `get_token_balance`\nReads the ERC-20 balance of any wallet address for a supported token.\n\nSupported tokens:\n- **Polygon:** `USDC`, `USDC.e`, `USDT`, `WETH`, `WMATIC`, `WBTC`, `DAI`, `AAVE`\n- **Arbitrum:** `USDC`, `USDC.e` (bridged), `USDT`, `WETH`, `WBTC`, `ARB`\n\n```json\n// get_token_balance(address=\"0x...\", token_symbol=\"USDC\", chain=\"polygon\")\n{\n  \"address\": \"0x...\",\n  \"token\": \"USDC\",\n  \"chain\": \"polygon\",\n  \"balance\": 268.21,\n  \"raw_balance\": \"268210000\",\n  \"decimals\": 6\n}\n```\n\n### `get_aave_position`\nReads a user's full Aave v3 lending/borrowing position: collateral, debt, available borrowing power, and health factor — straight from the Aave v3 Pool contract.\n\n```json\n// get_aave_position(address=\"0x...\", chain=\"polygon\")\n{\n  \"address\": \"0x...\",\n  \"chain\": \"polygon\",\n  \"total_collateral_usd\": 969.78,\n  \"total_debt_usd\": 288.16,\n  \"available_borrows_usd\": 484.86,\n  \"liquidation_threshold_pct\": 82.79,\n  \"ltv_pct\": 79.71,\n  \"health_factor\": 2.79,\n  \"has_active_position\": true\n}\n```\n\nA `health_factor` below `1.0` means the position is at risk of liquidation. A `null` health factor means the user has no outstanding debt.\n\n### `get_token_price`\nReads 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.\n\nSupported feeds:\n- **Polygon:** `ETH`/`WETH`, `MATIC`/`WMATIC`, `WBTC`, `USDC`, `USDT`\n- **Arbitrum:** `ETH`/`WETH`, `WBTC`, `ARB`, `USDC`, `USDT`\n\n```json\n// get_token_price(token_symbol=\"WBTC\", chain=\"polygon\")\n{\n  \"token\": \"WBTC\",\n  \"chain\": \"polygon\",\n  \"price_usd\": 63835.77,\n  \"decimals\": 8,\n  \"updated_at\": 1782032816\n}\n```\n\n### `simulate_swap`\nSimulates 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.\n\nSupported tokens:\n- **Polygon:** `USDC`, `USDC.e`, `USDT`, `WETH`, `WMATIC`, `WBTC`, `DAI`, `AAVE`\n- **Arbitrum:** `USDC`, `USDC.e` (bridged), `USDT`, `WETH`, `WBTC`, `ARB`\n\n```json\n// simulate_swap(token_in=\"WMATIC\", token_out=\"USDC\", amount_in=100.0, chain=\"polygon\")\n{\n  \"chain\": \"polygon\",\n  \"token_in\": \"WMATIC\",\n  \"token_out\": \"USDC\",\n  \"amount_in\": 100.0,\n  \"amount_out\": 7.990547,\n  \"fee_tier_used_pct\": 0.05,\n  \"fee_tier_used_bps\": 500,\n  \"gas_estimate\": 122770\n}\n```\n\nIf no pool exists for the pair at any fee tier, returns `{\"error\": \"No liquidity found for this pair on any fee tier\"}`.\n\n### `hello`\nSimple connectivity check — confirms the MCP server is reachable and responding.\n\n## Supported chains\n\n| Chain | `get_token_balance` | `get_aave_position` | `get_token_price` | `simulate_swap` |\n|---|---|---|---|---|\n| Polygon | ✅ | ✅ | ✅ | ✅ |\n| Arbitrum | ✅ | ✅ | ✅ | ✅ |\n\n## Installation\n\nRequires Python 3.10+ and an RPC provider API key (e.g. [Alchemy](https://www.alchemy.com/), free tier works).\n\n```bash\npip install defi-mcp\n```\n\nCreate a `.env` file in your working directory (see `.env.example`):\n\n```\nPOLYGON_RPC_URL=https://polygon-mainnet.g.alchemy.com/v2/YOUR_API_KEY\nARBITRUM_RPC_URL=https://arb-mainnet.g.alchemy.com/v2/YOUR_API_KEY\n```\n\nEach chain only needs its RPC URL configured. Tools called with `chain=\"arbitrum\"` will fail gracefully if `ARBITRUM_RPC_URL` is not set.\n\n## Usage with Claude Desktop\n\nAdd this to your Claude Desktop MCP config (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"defi-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"defi-mcp\"],\n      \"env\": {\n        \"POLYGON_RPC_URL\": \"https://polygon-mainnet.g.alchemy.com/v2/YOUR_API_KEY\",\n        \"ARBITRUM_RPC_URL\": \"https://arb-mainnet.g.alchemy.com/v2/YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop, and the tools above will be available to the model.\n\n## Testing locally\n\nYou can test the server directly with the official [MCP Inspector](https://github.com/modelcontextprotocol/inspector):\n\n```bash\nnpx @modelcontextprotocol/inspector uvx defi-mcp\n```\n\n## Roadmap\n\n- [ ] Track Uniswap v3 LP positions and impermanent loss\n- [ ] Monitor protocol TVLs\n- [ ] Additional chains (Ethereum, Base)\n- [ ] `defi-mcp-cloud` — hosted tier with MEV-specific tools, caching, and higher rate limits\n\n## Architecture\n\nOpen-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.\n\n## Resources\n\n- [defi-storage-cheatsheet](https://github.com/matiosera3-ops/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.\n\n## Contributing\n\nIssues and PRs welcome. This is an early-stage project — feedback on what tools would actually be useful to you is especially valuable.\n\n## License\n\nMIT\n\n<!-- mcp-name: io.github.matiosera3-ops/defi-mcp -->\n",
  "bytes": 5806,
  "sha": "31e9cd9c8bbcca24c820a075c833b38ad3b96bd04095663226be5cf32c236ad2",
  "repo_slug": "matiosera3-ops/defi-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_matiosera3_ops_defi_mcp_933e61f3/readme"
}