Blackhole MCP Server

Model Context Protocol server for the Blackhole DEX on Avalanche. Provides 26 tools for swaps, liquidity, CL positions, voting, locks, gauges, bribes, and yield queries.

Installation

As an npm package (for use with Blackhole Agent CLI)

npm install blackhole-mcp-server

import { startLocal } from "blackhole-mcp-server";

const { url, close } = await startLocal({ env: "devnet", port: 3100 });
// MCP server running at http://localhost:3100
// call close() to shut down

As a standalone server

git clone <repo-url>
cd mcp-server
yarn install
yarn serve:devnet     # http://localhost:3100

For MCP clients (Claude Desktop, Cursor, etc.)

No install needed -- just point your client config at the server.

Tools

| Category | Tools | |---|---| | Swap | swap_steps, quote | | Liquidity (V2) | add_liquidity_steps, remove_liquidity_steps, withdraw_liquidity_steps | | Liquidity (CL) | add_liquidity_cl_steps | | Zap | zap_add_liquidity_steps, zap_mint_cl_steps, zap_increase_liquidity_steps, zap_remove_liquidity_steps, zap_split_plan | | Staking | stake_liquidity_steps, unstake_liquidity_steps | | Fees & Emissions | claim_fees_steps, claim_emissions_steps, claim_voting_rewards_steps, claim_voting_rewards_payload | | Locks (veNFT) | create_lock_steps, increase_lock_steps, merge_lock_steps, lock_advanced_steps | | Voting | vote_steps | | Gauges & Bribes | create_gauge_steps, add_bribes_steps | | Pools | create_cl_pool_steps, pool_yield |

Transport Modes

1. Stdio -- for MCP clients (Claude Desktop, Cursor)

yarn dev              # devnet
yarn dev:mainnet      # mainnet

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "blackhole-mcp": {
      "command": "npx",
      "args": ["blackhole-mcp-server"]
    }
  }
}

Or from source:

{
  "mcpServers": {
    "blackhole-mcp": {
      "command": "bash",
      "args": ["-lc", "cd /path/to/mcp-server && NODE_ENV=prod npx tsx src/index.ts"]
    }
  }
}

Claude Desktop

Same config format as Cursor -- add it to your Claude Desktop MCP settings.

2. HTTP/SSE -- for hosting as a standalone server

yarn serve              # devnet on http://localhost:3100
yarn serve:devnet       # explicit devnet
yarn serve:mainnet      # mainnet

Custom port:

MCP_PORT=8080 yarn serve

Endpoints:

• GET /sse -- SSE connection for MCP clients
• POST /messages?sessionId=... -- JSON-RPC messages
• GET /health -- health check ({ status, tools })

3. Library -- import into your own Node.js app

npm install blackhole-mcp-server

import { startLocal } from "blackhole-mcp-server";

const { url, close } = await startLocal({ env: "devnet", port: 3100 });
// url = "http://localhost:3100"
// call close() to shut down

Options:

• env -- "devnet" (default) or "prod" / "mainnet"
• port -- default 3100

Environment

The server uses env-specific contract addresses and RPC URLs.

| Env | Network | RPC | |---|---|---| | devnet | Fuji Testnet | https://api.avax-test.network/ext/bc/C/rpc | | prod | Avalanche Mainnet | https://api.avax.network/ext/bc/C/rpc |

The setup-envs.js script copies the right constants from src/envs/{env}/constants/ into src/common/constants/. This runs automatically via npm scripts or programmatically via startLocal().

Env files:

• .env.devnet -- Fuji testnet contract addresses
• .env.prod -- Avalanche mainnet contract addresses

Development

git clone <repo-url>
cd mcp-server
yarn install
yarn dev              # stdio mode, devnet
yarn serve            # http mode, devnet

Publishing

# Build and publish to npm
npm run publish:npm

This runs prepublishOnly (build) automatically before publishing.

Publish order matters -- publish this package before blackhole-agent-cli, since the CLI depends on it.