MCP 服务器

valorem-mev-mcp

Gives MCP-compatible LLM agents direct access to real-time MEV and DeFi data via Valorem's x402-paid API endpoints, with payments in USDC on Base mainnet.

README

valorem-mev-mcp

Model Context Protocol (MCP) server for Valorem MEV Intelligence.

Gives any MCP-compatible LLM agent (Claude Desktop, ChatGPT, Cursor, etc.) direct access to real-time MEV and DeFi data via Valorem's x402-paid API endpoints. Payments are made in USDC on Base mainnet.

Tools

Tool	Endpoint	Cost	Description
`catalog`	`GET /catalog`	Free	Full service catalog with all endpoints and prices
`liquidation_watchlist`	`GET /liquidations/watchlist`	$0.50	Aave V3 near-liquidation positions — health factors, collateral, debt
`decoded_hints`	`GET /hints/decoded`	$0.10	Last 50 decoded MEV-Share hints — swap direction, pool, token pair
`builder_stats`	`GET /builders/stats`	$0.25	Per-builder acceptance rates for Flashbots, Titan, Beaver, BuilderNet, Quasar
`agent_intelligence`	`GET /agents/intelligence`	$1.00	Agent wallet tracking — active wallets, x402 spend patterns, top providers
`pool_spreads`	`GET /pools/spreads`	$0.05	L2 arb opportunities across 125+ Base + Arbitrum pools
`token_safety`	`GET /tokens/safety?token=`	$0.02	Token tax/rebase/reflect classification by contract address
`rpc_health`	`GET /rpc/health`	$0.01	RPC provider health — latency, error rates, uptime
`rpc_proxy`	`POST /rpc/proxy`	$0.001	Premium Reth L1 RPC proxy (~6 ms latency) — any JSON-RPC method

Payment Modes

Free Mode (default)

No private key required. When an API call returns HTTP 402, the server surfaces the payment requirements to the agent as a formatted message. The agent or user can then pay externally and retry.

npx valorem-mev-mcp

Paid Mode (auto-pay)

Set the PRIVATE_KEY environment variable to an EVM private key with USDC on Base mainnet. The server uses @x402/fetch + @x402/evm to automatically sign and submit payments, then retries the request transparently.

PRIVATE_KEY=0xYourPrivateKeyHere npx valorem-mev-mcp

Security: Never commit your private key. Use a dedicated spending wallet with only the USDC you intend to spend. The key never leaves your machine.

Installation

Global install

npm install -g valorem-mev-mcp
valorem-mev-mcp

npx (no install)

npx valorem-mev-mcp

Local development

git clone https://github.com/advalorem/valorem-mev-mcp
cd valorem-mev-mcp
npm install
node src/index.js

Connecting to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Free mode

{
  "mcpServers": {
    "valorem-mev": {
      "command": "npx",
      "args": ["valorem-mev-mcp"]
    }
  }
}

Paid mode

{
  "mcpServers": {
    "valorem-mev": {
      "command": "npx",
      "args": ["valorem-mev-mcp"],
      "env": {
        "PRIVATE_KEY": "0xYourPrivateKeyHere"
      }
    }
  }
}

Restart Claude Desktop after editing. The tools will appear in the tool selector.

Connecting to ChatGPT (Actions / Plugins)

ChatGPT plugins and Actions use an HTTP-based transport. To bridge this MCP server to HTTP, use mcp-proxy or the OpenAI MCP adapter:

# Install the bridge
npm install -g @modelcontextprotocol/proxy

# Run valorem-mev-mcp behind an HTTP proxy on port 3000
mcp-proxy --port 3000 -- npx valorem-mev-mcp

Then point your ChatGPT Action or plugin manifest at http://localhost:3000.

Connecting to Cursor / Windsurf / Other Clients

Most IDE-based MCP clients accept a command + args configuration identical to Claude Desktop. Add this to your client's MCP server list:

{
  "command": "npx",
  "args": ["valorem-mev-mcp"],
  "env": {
    "PRIVATE_KEY": "0xOptionalForAutoPay"
  }
}

Tool Usage Examples

Get service catalog (free)

Use the catalog tool to show me what MEV data is available.

Check near-liquidation positions

Call liquidation_watchlist and tell me which Aave V3 positions are closest to liquidation.

Classify a token

Use token_safety to check if 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 is a tax token.

Proxy an eth_call

Use rpc_proxy to call eth_blockNumber with params [].

Architecture

Claude / ChatGPT / Cursor
        │
        │  MCP stdio transport (JSON-RPC 2.0)
        ▼
valorem-mev-mcp  (this server)
        │
        │  HTTPS + optional x402 payment header
        ▼
https://18-220-76-66.nip.io/engine-api/x402
        │
        ▼
Valorem MEV Intelligence API (Base mainnet USDC payments)

x402 Payment Flow

1. Server calls API endpoint (no payment header)
2. API returns HTTP 402 with X-PAYMENT-REQUIRED header
3a. FREE mode: 402 details returned to agent as text
3b. PAID mode: @x402/fetch parses requirements, signs USDC EIP-712 permit
                with viem private key account, retries with X-PAYMENT header
4. API verifies payment, returns 200 with data