Content
# Sera MCP Server
[](LICENSE)
[](https://nodejs.org/)
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for **Sera** — the stablecoin exchange platform. Enables AI assistants like Claude to query market data, check balances, execute swaps, and manage orders through natural language.
## Features
- **Market Data** — Real-time stablecoin prices, metadata, and historical data
- **Wallet Management** — Check balances, token holdings, and exchange deposits
- **Trading** — Get quotes and execute swaps with automatic token approval
- **Order Management** — Place, view, and cancel limit orders
- **Deposit & Withdraw** — Move funds between wallet and exchange
- **Multi-Network** — Supports Ethereum mainnet and Sepolia testnet
## Quick Start
```bash
cd sera-mcp
npm install
npm run build
```
Then add the server to your Claude Desktop config. See [`claude_desktop_config.example.json`](./claude_desktop_config.example.json):
```json
{
"mcpServers": {
"sera": {
"command": "node",
"args": ["/path/to/sera-mcp/dist/index.js"],
"env": {
"EXTERNAL_API_URL": "https://api.dev.sera.cx",
"WALLET_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY",
"RPC_URL": "https://ethereum-sepolia-rpc.publicnode.com"
}
}
}
}
```
Config file location:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
Restart Claude Desktop after editing the config.
### Mainnet Configuration
```json
{
"env": {
"EXTERNAL_API_URL": "https://api.sera.cx",
"WALLET_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY",
"RPC_URL": "https://eth.llamarpc.com"
}
}
```
## Configuration
| Variable | Description | Default |
|----------|-------------|---------|
| `EXTERNAL_API_URL` | CLOB/trading API URL | `https://api.dev.sera.cx` |
| `WALLET_PRIVATE_KEY` | Private key for signing transactions (optional, enables execute tools) | - |
| `RPC_URL` | Ethereum RPC endpoint | `https://ethereum-sepolia-rpc.publicnode.com` |
**⚠️ Security Warning**: Never share or commit your `WALLET_PRIVATE_KEY`. Use a dedicated wallet for testing with limited funds.
## Available Tools
### Market Data
| Tool | Description |
|------|-------------|
| `get_market` | Get the complete stablecoin catalogue with live market data |
| `get_coin_metadata` | Get detailed metadata for a specific coin by ticker |
| `get_coin_history` | Get historical price data for a specific coin |
| `search_coins` | Search for stablecoins by name or ticker |
| `get_exchange_rate` | Get the exchange rate between two tokens |
### Wallet & Balance
| Tool | Description |
|------|-------------|
| `get_wallet_info` | Get configured wallet address, balance, and chain |
| `get_wallet_balances` | Get token balances (defaults to configured wallet) |
| `get_exchange_balance` | Get exchange (vault) balance (defaults to configured wallet) |
### Trading
| Tool | Description |
|------|-------------|
| `get_trading_pairs` | Get available trading pairs for a token |
| `get_swap_quote` | Get a price quote for swapping tokens |
| `get_clob_swap_quote` | Get a CLOB exchange swap quote |
| `prepare_swap` | Prepare a swap transaction (returns tx data to sign) |
| `execute_swap` | **Execute a swap end-to-end**: quote, approve if needed, sign EIP-712 intent, submit. Requires `WALLET_PRIVATE_KEY`. |
### Order Management
| Tool | Description |
|------|-------------|
| `place_limit_order` | Place a limit order |
| `get_open_orders` | Get all open orders (defaults to configured wallet) |
| `cancel_order` | Cancel an open order |
### Deposit & Withdraw
| Tool | Description |
|------|-------------|
| `prepare_deposit` | Prepare a deposit transaction (returns tx data to sign) |
| `prepare_withdraw` | Prepare a withdrawal transaction (returns tx data to sign) |
| `execute_deposit` | **Execute a deposit end-to-end**: builds tx, signs, sends on-chain. Requires `WALLET_PRIVATE_KEY`. |
| `execute_withdraw` | **Execute a withdrawal end-to-end**: builds tx, signs, sends on-chain. Requires `WALLET_PRIVATE_KEY`. |
## Example Prompts
Once configured, you can interact with Sera using natural language:
| Prompt | What it does |
|--------|-------------|
| "Check my wallet balances" | Calls `get_wallet_info` + `get_wallet_balances` |
| "Show me all stablecoins on Sera" | Calls `get_market` |
| "What's the exchange rate between USDT and USDC?" | Calls `get_exchange_rate` |
| "Swap 100 USDT for USDC" | Calls `execute_swap` with auto-approval |
| "Deposit 50 USDT to my exchange balance" | Calls `execute_deposit` |
| "Show my open orders and cancel the first one" | Calls `get_open_orders` + `cancel_order` |
## Key Behaviors
1. **Human-readable amounts**: All amount inputs (swap, deposit, withdraw) accept human-readable values like `"100"`. The server automatically converts to raw units (e.g., `100000000` for 6-decimal tokens) using token decimals fetched from the API.
2. **Automatic token approval**: `execute_swap` automatically checks if the input token has sufficient allowance for the SOR contract. If not (e.g., USDT which doesn't support EIP-2612 permit), it sends an on-chain `approve(spender, maxUint256)` transaction, waits for confirmation, refreshes the quote, then proceeds with the swap.
3. **EIP-712 signing**: Swap intents are signed using EIP-712 typed data (`Intent` type) with the Sera domain. The `uuid` field in `route_params` is a decimal big integer, not a UUID string.
4. **Authenticated endpoints**: `get_wallet_balances`, `get_open_orders`, and `get_exchange_balance` default to the configured wallet address. If a different `wallet_address` is provided, they return an info message instead of failing with 403.
5. **No-liquidity handling**: When the API returns a `no_liquidity` error (HTTP 400), the server returns a structured `{ status: "no_liquidity" }` response instead of a generic error.
6. **Testnet vs Mainnet**: Use `EXTERNAL_API_URL=https://api.dev.sera.cx` for testnet (Sepolia) or `https://api.sera.cx` for mainnet. The RPC URL must match the chain.
| Network | API URL | Chain ID | Example RPC |
|---------|---------|----------|-------------|
| Mainnet | `https://api.sera.cx` | 1 | `https://eth.llamarpc.com` |
| Sepolia | `https://api.dev.sera.cx` | 11155111 | `https://ethereum-sepolia-rpc.publicnode.com` |
## Development
```bash
# Run in dev mode with hot reload
EXTERNAL_API_URL=https://api.dev.sera.cx \
WALLET_PRIVATE_KEY=0x... \
npm run dev
```
## License
MIT
---
Built for [Sera](https://sera.cx) 🌐
Connection Info
You Might Also Like
No recommendations available