Blackhole MCP 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

Related MCP server: MCP-BAMM

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.

Optional runtime variables:

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.