Blackhole Server

Model Context Protocol server for the Blackhole DEX on Avalanche. Provides 48 tools for swaps, liquidity, CL positions, zaps, voting, locks, gauges, bribes, portfolio queries, pool analytics, gas estimation, and transaction execution.

Tools

Category	Tools
Swap	swap_steps, quote
Liquidity (V2)	add_liquidity_steps, remove_liquidity_steps, withdraw_liquidity_steps
Liquidity (CL)	add_liquidity_cl_steps, create_cl_pool_steps
Deposit math	get_deposit_amounts
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_rebase_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, get_lock_vote_state, vote_leaderboard
Epoch	get_epoch_state
Gauges & Bribes	create_gauge_steps, add_bribes_steps
Portfolio & discovery	resolve_address, get_token_balances, get_user_positions, get_user_locks, get_whitelisted_tokens, get_opportunities
Pools, yield & ALM	pool_yield, get_pool_status, get_pool_lp_providers, get_alm_vaults, get_tokenomics
CL math & simulation	cl_tick_to_price, cl_price_to_tick, cl_position_detail, cl_apr_simulator
Operational / Safety	get_allowances, estimate_gas_and_tx_cost
Execution	execute_transactions

Installation

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

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "blackhole-mcp": {
      "command": "npx",
      "args": ["@blackhole-dex/blackhole-mcp-server"],
      "env": {
        "PRIVATE_KEY": "0x..."
      }
    }
  }
}

Or from source:

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

Claude Desktop

Option A — one command (recommended):

From npm:

claude mcp add --scope user blackhole-mcp -- npx @blackhole-dex/blackhole-mcp-server

From source:

claude mcp add --scope user blackhole-mcp -- bash -lc "cd /path/to/mcp-server && NODE_ENV=prod npx tsx src/index.ts"

--scope user writes to your global Claude config (~/.claude.json) so the server is available in every project. Restart Claude Desktop after running.

Option B — manual JSON (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

From npm:

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

From source:

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

Restart Claude Desktop after editing the file.

Codex

Codex reads MCP server config from ~/.codex/config.toml (global) or .codex/config.toml (project-scoped, trusted projects only). The CLI and IDE extension share this file. See the Codex MCP docs for details.

Option A — Codex app / IDE (UI)

1. Open Settings (gear icon) in the Codex app or IDE extension.
2. Go to MCP settings and add a server (or choose Open config.toml and paste the TOML from Option C below).
3. Set the command to npx with args @blackhole-dex/blackhole-mcp-server, and add PRIVATE_KEY under environment variables if you plan to execute transactions.

Option B — CLI:

From npm:

codex mcp add blackhole-mcp --env PRIVATE_KEY=0x... -- npx @blackhole-dex/blackhole-mcp-server

From source:

codex mcp add blackhole-mcp --env PRIVATE_KEY=0x... -- bash -lc "cd /path/to/mcp-server && NODE_ENV=prod npx tsx src/index.ts"

In the Codex TUI, use /mcp to verify the server is active.

Option C — manual config.toml (~/.codex/config.toml or .codex/config.toml in the project):

From npm:

[mcp_servers.blackhole-mcp]
command = "npx"
args = ["@blackhole-dex/blackhole-mcp-server"]

[mcp_servers.blackhole-mcp.env]
PRIVATE_KEY = "0x..."

From source:

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

[mcp_servers.blackhole-mcp.env]
PRIVATE_KEY = "0x..."

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

npm install @blackhole-dex/blackhole-mcp-server

import { createMcpServer } from "@blackhole-dex/blackhole-mcp-server";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = createMcpServer();
const transport = new StdioServerTransport();
await server.connect(transport);

Options:

• Exported API: createMcpServer()
• Also exported: toolDefinitions, toolHandlers

Environment

The server uses production Avalanche mainnet configuration.

Env	Network	RPC
prod	Avalanche Mainnet	https://api.avax.network/ext/bc/C/rpc

Optional runtime variables:

Variable	Purpose
RPC_URL	Override the Avalanche C-Chain RPC endpoint used for reads and execution.
BASIC_GRAPH_URL	Override the basic pools subgraph URL.
CL_GRAPH_URL	Override the concentrated-liquidity subgraph URL.
GAMMA_VAULT_ADDRESSES	Comma-separated Gamma vault allowlist override.
PRIVATE_KEY	Private key used by execute_transactions. The server derives userAddress from this key for any tool that needs it.
USER_ADDRESS	Read-only fallback address when no private key is configured.

When PRIVATE_KEY is configured, tools with userAddress can omit it; the server fills in the private key-derived address. execute_transactions requires the private key and will only broadcast when called with confirm: true.