# BlackHoleDEX Mcp

> MCP server related details

- **Type:** MCP server
- **Install:** `agentstack add mcp-blackholedex-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [BlackHoleDEX](https://agentstack.voostack.com/s/blackholedex)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [BlackHoleDEX](https://github.com/BlackHoleDEX)
- **Source:** https://github.com/BlackHoleDEX/mcp

## Install

```sh
agentstack add mcp-blackholedex-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

| 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`)

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

Or from source:

```json
{
  "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:
```bash
claude mcp add --scope user blackhole-mcp -- npx @blackhole-dex/blackhole-mcp-server
```

From source:
```bash
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:
```json
{
  "mcpServers": {
    "blackhole-mcp": {
      "command": "npx",
      "args": ["@blackhole-dex/blackhole-mcp-server"]
    }
  }
}
```

From source:
```json
{
  "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](https://developers.openai.com/codex/mcp) 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:
```bash
codex mcp add blackhole-mcp --env PRIVATE_KEY=0x... -- npx @blackhole-dex/blackhole-mcp-server
```

From source:
```bash
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:
```toml
[mcp_servers.blackhole-mcp]
command = "npx"
args = ["@blackhole-dex/blackhole-mcp-server"]

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

From source:
```toml
[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

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

```ts
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`.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [BlackHoleDEX](https://github.com/BlackHoleDEX)
- **Source:** [BlackHoleDEX/mcp](https://github.com/BlackHoleDEX/mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-blackholedex-mcp
- Seller: https://agentstack.voostack.com/s/blackholedex
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.