# MCP Crypto Monitor — Crypto Wallet & Price Monitoring for AI Agents

> An MCP (Model Context Protocol) server that gives AI agents the ability to check crypto wallet balances, track token prices, calculate portfolio value, monitor gas prices, and track the Fear & Greed Index — all with zero external dependencies using free public APIs.

## Why This Exists

Crypto monitoring tools typically require API keys, paid subscriptions, or heavy SDK installations. This MCP server uses **only free public APIs** (Blockchain.info, Etherscan, CoinGecko, Binance) with **zero pip dependencies** — pure Python stdlib. Your AI agent gets 10 crypto monitoring tools out of the box.

**No API keys. No paid subscriptions. No pip installs. Just Python stdlib + internet.**

## Features

- **10 MCP Tools**: `get_btc_balance`, `get_eth_balance`, `get_erc20_balance`, `get_btc_transactions`, `get_price`, `get_price_binance`, `get_portfolio_value`, `get_gas_price`, `get_fear_greed`, `monitor_address`
- **Zero dependencies** — pure Python stdlib (urllib, json)
- **Free APIs only** — Blockchain.info, Etherscan, CoinGecko, Binance, alternative.me
- **Portfolio calculation** — pass your holdings, get total USD value instantly
- **STDIO JSON-RPC mode** — drop-in for Claude Desktop, Hermes, or any MCP client
- **BTC + ETH + ERC20** — address balance checks with transaction history

## Quick Start

```bash
# STDIO mode (for MCP clients)
python -m src.server --stdio

# Or print the manifest
python -m src.server --manifest
```

### Use as a library

```python
from src.server import MCPCryptoMonitorServer
import json

server = MCPCryptoMonitorServer()

# Get BTC balance
result = server.handle_tool_call("get_btc_balance", {"address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"})
print(json.loads(result))

# Get portfolio value
result = server.handle_tool_call("get_portfolio_value", {
    "holdings": {"BTC": 0.5, "ETH": 10.0, "USDT": 5000.0}
})
print(json.loads(result)["total_value_usd"])

# Get current prices
result = server.handle_tool_call("get_price", {"coins": ["bitcoin", "ethereum", "monero"]})

# Get ETH gas price
result = server.handle_tool_call("get_gas_price", {})

# Get Fear & Greed Index
result = server.handle_tool_call("get_fear_greed", {})
```

## MCP Tool Reference

| Tool | Description | Required Params |
|------|-------------|-----------------|
| `get_btc_balance` | BTC address balance (satoshis + BTC) | `address` |
| `get_eth_balance` | ETH address balance (wei + ETH) | `address` |
| `get_erc20_balance` | ERC20 token balance | `address`, `token_contract` |
| `get_btc_transactions` | Recent BTC transactions | `address` |
| `get_price` | Prices from CoinGecko | `coins` |
| `get_price_binance` | Price from Binance | `pair` |
| `get_portfolio_value` | Total portfolio in USD | `holdings` |
| `get_gas_price` | ETH gas price (low/std/high gwei) | — |
| `get_fear_greed` | Crypto Fear & Greed Index | — |
| `monitor_address` | Balance + transactions in one call | `address`, `coin` |

## Integration with MCP Clients

### Claude Desktop

```json
{
  "mcpServers": {
    "crypto-monitor": {
      "command": "python",
      "args": ["-m", "src.server", "--stdio"],
      "cwd": "/path/to/mcp-crypto-monitor"
    }
  }
}
```

### Hermes Agent

```yaml
mcp:
  servers:
    crypto-monitor:
      command: python
      args: ["-m", "src.server", "--stdio"]
      cwd: /path/to/mcp-crypto-monitor
```

## Tests

```bash
python -m pytest tests/ -v  # 30 tests, all passing
```

## API Sources

| API | Usage | Key Required |
|-----|-------|-------------|
| Blockchain.info | BTC balance + transactions | No |
| Etherscan | ETH balance + gas price | No (rate-limited) |
| CoinGecko | Token prices | No |
| Binance | Trading pair prices | No |
| alternative.me | Fear & Greed Index | No |

## License

MIT

## Author

aaameobius-crypto — [github.com/aaameobius-crypto](https://github.com/aaameobius-crypto)

Freelance portfolio: [https://ameobius-space.github.io/kwork-portfolio/](https://ameobius-space.github.io/kwork-portfolio/)