Metadata-Version: 2.4
Name: defi-mcp
Version: 0.1.1
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

<!-- mcp-name: 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. 4 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
}
```

### `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
git clone https://github.com/matiosera3-ops/defi-mcp.git
cd defi-mcp
python -m venv venv

# Windows
.\venv\Scripts\Activate.ps1
# macOS/Linux
source venv/bin/activate

pip install -e .
```

Create a `.env` file in the project root:

```
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": "python",
      "args": ["/absolute/path/to/defi-mcp/server.py"]
    }
  }
}
```

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 python server.py
```

## Roadmap

- [ ] Track Uniswap v3 LP positions and impermanent loss
- [ ] Simulate swaps with realistic slippage estimates
- [ ] 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
