Metadata-Version: 2.4
Name: defi-mcp
Version: 0.1.4
Summary: An MCP server giving AI agents access to DeFi data on EVM chains.
Author-email: Matthieu Ratsitohery <matiosera3@gmail.com>
License: MIT
Project-URL: Repository, https://github.com/matiosera3-ops/defi-mcp
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: web3>=7.0.0
Requires-Dist: python-dotenv>=1.0.0
Dynamic: license-file

# 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 on Polygon: `USDC`, `USDC.e`, `USDT`, `WETH`, `WMATIC`, `WBTC`, `DAI`, `AAVE`.

```json
// 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.

```json
// 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 on Polygon: `ETH`/`WETH`, `MATIC`/`WMATIC`, `WBTC`, `USDC`, `USDT`.

```json
// 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 on Polygon: `USDC`, `USDC.e`, `USDT`, `WETH`, `WMATIC`, `WBTC`, `DAI`, `AAVE`.

```json
// 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

- Polygon

More EVM chains are on the roadmap (see below).

## Installation

Requires Python 3.10+ and an RPC provider API key (e.g. [Alchemy](https://www.alchemy.com/), free tier works).

```bash
pip install defi-mcp
```

Create a `.env` file in your working directory:

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

## Usage with Claude Desktop

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

```json
{
  "mcpServers": {
    "defi-mcp": {
      "command": "uvx",
      "args": ["defi-mcp"],
      "env": {
        "POLYGON_RPC_URL": "https://polygon-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](https://github.com/modelcontextprotocol/inspector):

```bash
npx @modelcontextprotocol/inspector uvx defi-mcp
```

## Roadmap

- [ ] Track Uniswap v3 LP positions and impermanent loss
- [ ] Monitor protocol TVLs
- [ ] Additional chains (Ethereum, Arbitrum, 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.

## 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

<!-- mcp-name: io.github.matiosera3-ops/defi-mcp -->
