npm package: @onlyswaps/mcp-server
Description: Give your Privy wallet swap superpowers. Multi-chain DEX meta-aggregator for AI agents - queries 15+ DEX aggregators for best swap prices.
Author: OnlySwaps
Latest version: 0.2.3

# OnlySwaps MCP Server

> **Multi-chain DEX meta-aggregator for AI agents.** Queries 15+ DEX aggregators, returns the best price.

MCP (Model Context Protocol) server that enables AI agents to execute token swaps. We query 0x, 1inch, Paraswap, DODO, Uniswap, Li.Fi, and 10+ more sources, returning only the best available quotes.

## Why OnlySwaps?

- **Meta-Aggregator**: Queries 15+ DEX aggregators (0x, 1inch, Paraswap, Li.Fi, etc.) and returns the best available price
- **13 Chains**: Ethereum, Base, Arbitrum, Optimism, Polygon, BSC, Avalanche, Solana, and more
- **One Integration**: Single API call to access all DEX liquidity across all chains
- **AI-Native**: Built for MCP - works with Claude Desktop, Cursor, and any MCP client

## Tools

| Tool | Description |
|------|-------------|
| `get_quote` | Get swap quotes from multiple DEX aggregators |
| `build_swap_tx` | Build unsigned swap transaction (ready for client-side signing) |
| `execute_swap` | Execute swap end-to-end with embedded wallet (Privy) |
| `get_portfolio` | Get user token holdings across chains |
| `get_tx_status` | Check transaction status |
| `estimate_gas` | Estimate gas for a transaction |
| `search_token` | Search tokens by name or symbol |

## Quick Start

### Using npx

```bash
npx @onlyswaps/mcp-server
```

### Claude Desktop Configuration

Add to `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "onlyswaps": {
      "command": "npx",
      "args": ["-y", "@onlyswaps/mcp-server", "stdio"],
      "env": {
        "ONLYSWAPS_API_URL": "https://api.onlyswaps.fyi"
      }
    }
  }
}
```

### Hosted Server (SSE)

Connect to our hosted MCP server:

```
https://mcp.onlyswaps.fyi/mcp
```

## Supported Chains

| Chain | ID | Native Token |
|-------|-----|--------------|
| Ethereum | 1 | ETH |
| Optimism | 10 | ETH |
| BSC | 56 | BNB |
| Gnosis | 100 | xDAI |
| Polygon | 137 | MATIC |
| Fantom | 250 | FTM |
| zkSync Era | 324 | ETH |
| Base | 8453 | ETH |
| Arbitrum | 42161 | ETH |
| Avalanche | 43114 | AVAX |
| Linea | 59144 | ETH |
| Scroll | 534352 | ETH |
| Solana | solana | SOL |

## Tool Examples

### get_quote

Get the best swap quote across all aggregators.

```json
{
  "fromToken": "ETH",
  "toToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": "1000000000000000000",
  "chainId": "base"
}
```

Returns:
```json
{
  "bestQuote": {
    "provider": "1inch",
    "buyAmount": "3245000000",
    "sellAmount": "1000000000000000000",
    "estimatedGas": "150000",
    "priceImpact": "0.05"
  },
  "allQuotes": [...],
  "meta": { "chain": "Base", "chainId": 8453, "sourcesQueried": 5 }
}
```

### build_swap_tx

Build an unsigned transaction ready for client-side signing.

```json
{
  "fromToken": "ETH",
  "toToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": "1000000000000000000",
  "chainId": "base",
  "userAddress": "0xYourWalletAddress",
  "slippage": 1
}
```

Returns transaction data (`to`, `data`, `value`, `gas`, `chainId`) ready to sign.

### execute_swap

Execute a swap end-to-end using an embedded Privy wallet. Requires Privy configuration.

```json
{
  "fromToken": "ETH",
  "toToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": "1000000000000000000",
  "chainId": "base",
  "userId": "privy-user-id"
}
```

### get_portfolio

Get user token holdings across all supported chains.

```json
{
  "address": "0xYourWalletAddress",
  "chainIds": ["ethereum", "base", "arbitrum"]
}
```

### get_tx_status

Check the status of a transaction.

```json
{
  "txHash": "0xabc123...",
  "chainId": "base"
}
```

### estimate_gas

Estimate gas for a swap transaction.

```json
{
  "fromToken": "ETH",
  "toToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": "1000000000000000000",
  "chainId": "base",
  "userAddress": "0xYourWalletAddress"
}
```

### search_token

Search for tokens by name or symbol.

```json
{
  "query": "USDC",
  "chainId": "base"
}
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_PORT` | `3001` | HTTP server port |
| `MCP_TRANSPORT` | `http` | Transport mode: `http` or `stdio` |
| `ONLYSWAPS_API_URL` | - | OnlySwaps backend API URL |
| `ONLYSWAPS_API_KEY` | - | API key for authenticated access |
| `CORS_ORIGINS` | `*` | Comma-separated CORS origins |
| `PRIVY_APP_ID` | - | Privy App ID (for `execute_swap`) |
| `PRIVY_APP_SECRET` | - | Privy App Secret (for `execute_swap`) |
| `PRIVY_AUTHORIZATION_PRIVATE_KEY` | - | Privy auth key (for `execute_swap`) |

## Running Locally

```bash
# Install dependencies
pnpm install

# Build
pnpm build

# Run HTTP server
pnpm start

# Run stdio mode (for Claude Desktop)
node dist/index.js stdio
```

## Docker

```bash
docker build -t onlyswaps-mcp .
docker run -p 3001:3001 \
  -e ONLYSWAPS_API_URL=https://api.onlyswaps.fyi \
  onlyswaps-mcp
```

## API Endpoints

| Endpoint | Description |
|----------|-------------|
| `GET /health` | Health check |
| `GET /capabilities` | Supported chains and tools |
| `GET /mcp` | MCP SSE connection endpoint |
| `POST /mcp/messages` | MCP message handler |

## Links

- **Website**: https://onlyswaps.fyi
- **Hosted MCP**: https://mcp.onlyswaps.fyi
- **GitHub**: https://github.com/Delegueinu/onlyswaps

## License

MIT