npm package: @heightslabs/mcp-heightslabs
Description: MCP server interface for the Heights Labs API
Author: Heights Labs
Latest version: 0.4.2

# @heightslabs/mcp-heightslabs

MCP server interface for the Heights Labs blockchain analytics API.

This server exposes Heights Labs operations for cluster analysis, chain data, transaction flows, network intelligence, attributions, watchlists, blacklists, and admin utilities via FastMCP tools.

## Features

- FastMCP stdio server (`mcp-heightslabs`)
- Heights Labs API key support via hidden tool arg (`apiKey`) or env fallback (`HL_API_KEY`)
- Heights Labs base URL override via hidden tool arg (`baseUrl`) or env fallback (`HL_BASE_URL`)
- Automatic HTTP 429 retries with exponential backoff and env-configured retry limit
- Strict TypeScript and Zod-validated tool inputs
- 120 defined tools (`110` active, `10` disabled) covering blockchain analytics, fund flow tracing, network intelligence, entity attribution, and composite investigator workflows
- Build/test CI and npm publish workflow

## Requirements

- Node.js `>=20`
- Yarn

## Installation

```bash
yarn install
yarn build
yarn start
```

Run as CLI after install/publish:

```bash
mcp-heightslabs
```

## Configuration

| Variable | Required | Default | Description |
|---|---|---|---|
| `HL_API_KEY` | No | unset | Heights Labs API key fallback when hidden `apiKey` is not passed |
| `HL_BASE_URL` | No | `https://api.heightslabs.com` | Base URL for API endpoints |
| `HL_HTTP_TIMEOUT_MS` | No | `120000` | Request timeout in milliseconds |
| `HL_MAX_429_RETRIES` | No | `3` | Maximum number of automatic retries for HTTP 429 responses before surfacing the error |

## Hidden Arguments

The following are intentionally not in tool schemas and are injected as hidden extra args at runtime:

- `apiKey`: Heights Labs API key for request authentication (`x-api-key` header)
- `baseUrl`: Optional base URL override

Resolution order per request:

1. Hidden extra arg
2. Environment fallback

If no API key is available, the tool returns a user-facing error.

## Tool Surface (120 defined tools, 110 active by default)

### Events

| Tool | Description |
|---|---|
| `hl_get_clients` | List all currently connected WebSocket/event clients. Returns a map of client identifiers to connection counts, plus a total count. |

### Clusters

| Tool | Description |
|---|---|
| `hl_get_cluster_for_address` | Look up the cluster that a single blockchain address belongs to. A cluster groups addresses believed to be controlled by the same entity. Returns Cluster (id, size, topAttribution, topCategory) or null if not clustered. |
| `hl_get_clusters_for_address_list` | Bulk look up clusters for multiple addresses at once. Returns a map of address -> Cluster for each address that belongs to a cluster. Optionally include externalAttributions for custom attribution data. |
| `hl_get_cluster_addresses` | List all blockchain addresses belonging to a specific cluster by cluster ID. Returns a paginated list of addresses with pagination metadata (total count, next page, total pages). |
| `hl_get_cluster_addresses_by_attribution` | List blockchain addresses belonging to clusters that share a given attribution label (e.g., 'Binance'). Returns a paginated list of addresses with pagination metadata. |
| `hl_get_cluster_addresses_by_attribution_count` | Count the total number of addresses in clusters that share a given attribution label. Returns a number. |

### Chain (Blocks & Transactions)

| Tool | Description |
|---|---|
| `hl_get_block` | Fetch a single block by height or hash on a blockchain network. Returns block data including hash, height, timestamp, and transaction list. |
| `hl_get_blocks` | Fetch multiple blocks within a range, paginated by height or date. Returns an array of block objects. |
| `hl_get_block_summary` | Fetch a condensed summary of a single block by height or hash. Returns key block info without full transaction details. |
| `hl_get_block_summaries` | Fetch condensed summaries for multiple blocks within a range. Returns an array of block summaries without full transaction details. |
| `hl_get_latest_block` | Fetch the most recently mined/confirmed block on a blockchain network. Returns the latest block data. |
| `hl_get_transaction` | Fetch a single transaction by its hash/ID on a blockchain network. Returns full transaction details including inputs, outputs, and amounts. |
| `hl_get_transactions` | List all transactions within a specific block by block height or hash. Returns an array of transactions. |
| `hl_get_transactions_in_list` | Batch fetch multiple transactions by providing a list of transaction IDs. Optionally return only headers for lighter responses. Returns an array of transaction objects. |
| `hl_get_transactions_page` | Fetch a paginated page of transactions for a specific block. Use this instead of hl_get_transactions when the block has many transactions. |
| `hl_get_receipts` | Fetch event logs and receipts for a specific transaction on EVM-compatible chains. Returns an array of log events or transaction receipts. |
| `hl_get_receipts_bulk` | Batch fetch event logs and receipts for multiple transactions at once on EVM-compatible chains. |
| `hl_get_receipts_for_block` | Fetch all event logs and receipts for every transaction in a specific block on EVM-compatible chains. |
| `hl_find_input` | Find the spending input that consumed a specific UTXO output. Given a transaction hash and output index (vout), returns the input that later spent those funds. |

### Chain (Ledger)

| Tool | Description |
|---|---|
| `hl_get_symbols` | List all supported token and asset symbols for a blockchain network. Use this to discover which assets can be queried in ledger operations. |
| `hl_get_cluster_ledger` | Fetch paginated transaction history for a cluster. Supports sorting, filtering by amount/time, aggregation, and attribution breakdown. |
| `hl_get_cluster_ledger_count` | Count the total number of transactions in a cluster's ledger. Supports the same filters as hl_get_cluster_ledger. Returns a number. |
| `hl_get_address_ledger` | Fetch paginated transaction history for a single blockchain address. Same capabilities as hl_get_cluster_ledger (sorting, filtering, aggregation) but scoped to one address. |
| `hl_get_address_ledger_count` | Count the total number of transactions in an address's ledger. Supports the same filters as hl_get_address_ledger. Returns a number. |
| `hl_get_filtered_ledger` | Query the ledger with custom filters without specifying a particular entity (address or cluster). Useful for broad transaction searches with amount, time, and attribution constraints. |
| `hl_get_filtered_ledger_count` | Count the total number of transactions matching a filtered ledger query. Returns a number. |
| `hl_get_transaction_ledger` | Fetch detailed ledger entries (inputs and outputs) for a single transaction, enriched with cluster and attribution data. Supports grouping, aggregation, and field selection. |
| `hl_get_transaction_ledger_count` | Count the total number of ledger entries (inputs/outputs) for a single transaction. Returns a number. |
| `hl_get_transaction_ledger_bulk` | Batch fetch ledger entries for multiple transactions at once. Provide a list of transaction I/O triplets to get enriched input/output data with cluster and attribution info. |
| `hl_get_counterparties` | List all transaction counterparties for an entity (address, cluster, or attribution) with aggregated amounts. Use this to see who an entity has transacted with and how much. |
| `hl_get_summary` | Get summary statistics for an entity (address, cluster, or attribution). Returns first/last transaction time and per-symbol balances including credits, deductions, current balance, and transaction count. |
| `hl_get_links_summaries` | Get summary statistics for transaction links between pairs of entities. Provide pairs of entity IDs to see aggregated transaction data between them. |
| `hl_get_link_transactions` | Fetch individual transactions between two linked entities, paginated and sortable. Use after hl_get_links_summaries to drill into the actual transactions between a pair. |

### Chain (Stats & Accounts)

| Tool | Description |
|---|---|
| `hl_get_supported_assets` | List supported token and asset types for a blockchain network. Use this to discover which assets are available for statistics queries. |
| `hl_get_stats` | Fetch time-series statistics for a network asset (price, volume, etc.) over a date range at a specified interval. Use hl_get_supported_assets first to find valid asset names. |
| `hl_get_supported_accounts` | List supported ledger account types for a blockchain network. Use this to discover valid account types for account ledger queries. |
| `hl_get_account_ledger` | Fetch account-style ledger entries within a time range. Returns an array of ledger transactions for the specified account type. |
| `hl_get_account_ledger_recent` | Fetch the most recent account ledger entries, limited by count. Returns an array of the latest ledger transactions. |

### Flows

Fund flow tracing for source-of-funds and destination-of-funds analysis. Flows trace the movement of value through the blockchain transaction graph.

| Tool | Description |
|---|---|
| `hl_get_flows` | Trace the flow of funds from specific transaction outputs (source-of-funds or destination-of-funds analysis). Returns paginated flow results showing amounts, shortest paths, and attribution data. |
| `hl_get_heuristics` | Apply change-detection heuristics to transaction inputs/outputs to identify likely change outputs. Useful for determining which outputs return funds to the sender vs. paying the recipient. |
| `hl_get_flows_count` | Count the total number of flows matching given criteria without fetching them. Returns a number. Use before hl_get_flows to estimate result size. |
| `hl_get_flow` | Get the detailed flow between a specific source and destination transaction. Returns the complete fund flow path with amounts and intermediary data. |
| `hl_get_intersection` | Find where fund flows from a source and destination intersect, revealing common intermediary transactions. Useful for proving connections between two entities. |
| `hl_get_aggregate_flows` | Search aggregated fund flows grouped by source/destination attributes (address, cluster, attribution, or category). Supports filtering and exclusion for targeted analysis. |
| `hl_get_attributed_flows` | Search fund flows that include attribution labels on sources and destinations. Sortable and filterable by source/destination attributes. Returns enriched flow data with entity identities. |
| `hl_get_aggregate_flow_hierarchies` | Get a hierarchical tree of aggregated fund flows, useful for visualization. Drill down by attribution, address, or cluster with configurable depth levels. |
| `hl_get_raw_flows` | Fetch raw, unprocessed fund flows to a destination with address-level detail. Returns flows before aggregation or attribution enrichment. |
| `hl_get_filtered_flows` | Filter a set of raw flows by address list and external attributions. Use after hl_get_raw_flows to narrow results to specific addresses of interest. |
| `hl_pathfind` | Find the shortest transaction paths from an address or cluster to categorized entities (e.g., exchanges, mixers, gambling). Useful for tracing how funds reach or originate from known services. |
| `hl_cluster_flow_categories` | Get a breakdown of a cluster's fund flows by risk/entity category (e.g., exchange, gambling, mining, illicit). Shows what types of entities the cluster has transacted with. |
| `hl_cluster_flow_attributions` | Get a paginated breakdown of a cluster's fund flows by specific attribution (e.g., 'Binance', 'Coinbase'). Shows which identified entities the cluster has transacted with and the amounts. |
| `hl_cluster_attribution_flows` | Fetch individual flow transactions between a cluster and a specific attribution. Sortable by amount or time. Use after hl_cluster_flow_attributions to drill into specific entity relationships. |

### Composite Investigation Helpers

| Tool | Description |
|---|---|
| `hl_trace_entity_exposure` | Build a unified exposure summary for an address, cluster, or attribution by combining category exposure, top attributions, counterparties, and pathfinding results. |
| `hl_trace_utxo_provenance` | Trace deterministic Bitcoin UTXO provenance from one or more txid:vout seeds, including stop reasons and heuristic ambiguity notes. |
| `hl_detect_peel_chain` | Detect and follow candidate Bitcoin peel chains conservatively from a seed transaction, address, or cluster. |
| `hl_trace_stablecoin_control_flow` | Summarize stablecoin transfer and control-surface evidence for a supported-chain address, including counterparties and investigator notes. |
| `hl_trace_tron_asset_flow` | Build a TRON-first asset-flow summary using Heights ledger, counterparty, and attribution primitives. |
| `hl_build_investigation_bundle` | Create a one-shot investigation bundle for a seed address or transaction, combining common Heights enrichment outputs into a single payload. |

### Alerts

| Tool | Description |
|---|---|
| `hl_get_alerts` | Fetch paginated watchlist alerts triggered when watched blockchain addresses transact. Returns an array of alert objects with transaction details. |
| `hl_get_investigation_alerts` | Fetch watchlist alerts filtered to a specific investigation. Same as hl_get_alerts but scoped to addresses within a named investigation. |

### Authentication

| Tool | Description |
|---|---|
| `hl_authenticated` | Verify a user's authentication status by username. Returns authentication details for the specified user. |
| `hl_check_auth` | Check if the current API session is authenticated. Returns the authentication status. |

### Admin

| Tool | Description |
|---|---|
| `hl_send_invite` | Send an email invitation to a new user to join the Heights Labs platform. Requires admin privileges. |
| `hl_get_users` | List all registered users on the Heights Labs platform. Requires admin privileges. Returns an array of user objects. |
| `hl_get_active_users` | List currently active users on the Heights Labs platform. Requires admin privileges. |
| `hl_get_rate_limits` | Check the current rate limit status for given API key IDs. Returns remaining quota and reset timing information. |

### Attributions

Attributions are identity labels assigned to blockchain clusters and addresses (e.g., "Binance", "FBI Seized Funds", "Coinbase"). They link on-chain activity to real-world entities.

| Tool | Description |
|---|---|
| `hl_get_attributions` | Look up attribution labels for a list of blockchain addresses. Returns a map of address to attribution array, each with ID, networks, categories, and source. |
| `hl_get_clusters_for_attribution` | List clusters that share a given attribution label, paginated. Use this to find all clusters associated with a known entity. |
| `hl_get_clusters_for_attribution_count` | Count the total number of clusters that share a given attribution label. Returns a number. |
| `hl_get_attribution_categories` | List all available attribution categories with their name, code, and risk score. Categories classify entities by type (e.g., exchange, gambling, mining, illicit). |

### Search

| Tool | Description |
|---|---|
| `hl_search_attributions` | Full-text search for attribution labels by name. Use mode 'match' for exact matching or 'wildcard' for partial matches. |
| `hl_autocomplete_attributions` | Type-ahead autocomplete for attribution search. Use mode 'wildcard' or 'suggest'. Returns matching attribution names and a total count. Optionally filter by network. |
| `hl_search_attribution_names` | Full-text search for attribution display names. Similar to hl_search_attributions but searches the human-readable display name field. |
| `hl_autocomplete_attribution_names` | Type-ahead autocomplete for attribution display names. Searches display names instead of raw attribution identifiers. |
| `hl_get_attribution_names` | List all attribution names for a blockchain network, paginated. Use this to browse available attributions without searching. |
| `hl_search_addresses` | Full-text search for blockchain addresses. Use this to find addresses matching a partial or full address string. |
| `hl_autocomplete_addresses` | Type-ahead autocomplete for blockchain address search. Returns matching addresses as the user types. Optionally filter by network. |
| `hl_search_transactions` | Full-text search for transaction hashes. Use this to find transactions matching a partial or full hash string. |

### Network Intelligence

P2P network monitoring, node discovery, and Electrum protocol surveillance tools.

| Tool | Description |
|---|---|
| `hl_get_first_seen_by_hash` | Find the first network node that broadcast a specific transaction hash. Useful for identifying the origin of a transaction on the P2P network. |
| `hl_get_first_seen_by_ip` | List transaction hashes that were first seen being broadcast from a specific IP address on the P2P network. |
| `hl_get_node_by_ip` | Get blockchain node information by IP address. Returns node details including version, services, and connection info. |
| `hl_get_all_nodes` | List all known blockchain nodes on a network. Returns node details for the entire network. |
| `hl_get_network_stats` | Get aggregate statistics for a blockchain network including protocol distribution, user agents, services, countries, and ASN breakdown. |
| `hl_get_cluster_ips` | Get a mapping of cluster IDs to their associated IP addresses with connection counts. |

### Electrum Protocol Monitoring

SPV wallet tracking via Electrum protocol analysis. Links lightweight wallet activity to IP addresses and blockchain addresses.

| Tool | Description |
|---|---|
| `hl_get_electrum_peers` | List all Electrum server peers on a blockchain network. Returns peer details including IP, protocol versions, geolocation, and first/last seen timestamps. |
| `hl_get_electrum_peer` | Get details for a single Electrum server peer by IP address. |
| `hl_get_electrum_users` | List Electrum protocol users/clients on a blockchain network, with optional statistics. |
| `hl_get_electrum_user` | Get details for a single Electrum user/client by IP address. |
| `hl_get_electrum_transactions` | Get a map of all Electrum-monitored transactions grouped by address. |
| `hl_get_transactions_for_ip` | Get Electrum transactions associated with a specific IP address. |
| `hl_get_electrum_users_with_transactions` | List Electrum users that have associated transaction activity. Filters out idle connections. |
| `hl_get_electrum_wallets_by_network` | List a summary of all Electrum wallets detected on a blockchain network, with optional statistics. |
| `hl_get_electrum_watchlists_by_network` | List watched Electrum wallets on a blockchain network. Returns wallets that are actively being monitored. |
| `hl_get_electrum_wallet_addresses` | Get all blockchain addresses contained in a specific Electrum wallet by wallet ID. |
| `hl_get_electrum_wallet_clusters` | Get the blockchain clusters associated with a specific Electrum wallet. Links SPV wallet data to on-chain cluster analysis. |
| `hl_get_electrum_wallets_by_ip` | Find Electrum wallets that have connected from a specific IP address. |
| `hl_get_electrum_wallet_by_address` | Find which Electrum wallet contains a specific blockchain address. |
| `hl_get_electrum_wallets_by_cluster` | Map Electrum wallets to their corresponding blockchain clusters. |

### Electrum Statistics

Time-series data for Electrum protocol activity. All return arrays of `{count, start, end}` data points.

| Tool | Description |
|---|---|
| `hl_get_peer_counts` | Electrum peer count over time. |
| `hl_get_user_counts` | Electrum user count over time. |
| `hl_get_transaction_counts` | Electrum transaction count over time. |
| `hl_get_wallet_counts` | Electrum wallet count over time. |
| `hl_get_watchlist_counts` | Electrum watchlist hit count over time. |
| `hl_get_wallet_address_counts` | Electrum wallet address count over time. |

### IP & Geolocation

| Tool | Description |
|---|---|
| `hl_get_geo_list` | List all available geographic regions with their name and code. |
| `hl_get_ip` | Get detailed information for a single IP address including geolocation, ASN, network carrier, and threat indicators. |
| `hl_get_ips` | Batch look up detailed information for multiple IP addresses. |
| `hl_get_ips_near_geo` | Find IP addresses near a specified geographic location. |
| `hl_get_ips_within_country` | Find all IP addresses within a specific country. |
| `hl_get_asns` | List all Autonomous System Numbers (ASNs) associated with blockchain nodes. |
| `hl_get_carriers` | List all network carriers and ISPs hosting blockchain nodes. |
| `hl_get_countries` | List all countries where blockchain nodes are present. |
| `hl_get_regions` | List all geographic regions where blockchain nodes are present. |
| `hl_get_cities` | List all cities where blockchain nodes are present. |
| `hl_get_ips_by_address` | Find IP addresses associated with a blockchain address via Electrum protocol monitoring. |
| `hl_get_addresses_by_ip` | Find blockchain addresses associated with an IP address via Electrum protocol monitoring, paginated. |

### Watchlist

| Tool | Description |
|---|---|
| `hl_get_watchlist` | Get watched blockchain addresses for a user, optionally filtered by investigation. Returns an array of watchlist address entries that are being monitored for activity. |
| `hl_add_watchlist_addresses` | Add blockchain addresses to the watchlist for real-time monitoring. When watched addresses transact, alerts will be generated. |

### Blacklist

| Tool | Description |
|---|---|
| `hl_get_blacklist` | Get blacklisted blockchain addresses for a user, optionally filtered by investigation. Returns addresses flagged as high-risk or sanctioned. |
| `hl_get_categories` | List all available blacklist categories. Returns an array of category names used to classify blacklisted addresses. |

### Validation

| Tool | Description |
|---|---|
| `hl_validate_address` | Validate a blockchain address format and detect which network(s) it belongs to (e.g., bitcoin, ethereum). Returns validation status and detected networks. |
| `hl_validate_addresses_batch` | Batch validate multiple blockchain addresses at once. Returns validation results and detected networks for each address. |

## Response Format

All tool handlers return deterministic JSON text strings. Parse text content on the client side if structured access is needed.

## Usage Examples

### JSON-RPC tools/call with hidden API key

```json
{
  "method": "tools/call",
  "params": {
    "name": "hl_get_cluster_for_address",
    "arguments": {
      "network": "bitcoin",
      "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
      "apiKey": "hl-..."
    }
  }
}
```

### FastMCP-style client call

```ts
await client.callTool('hl_get_transaction', {
  network: 'ethereum',
  id: '0xabc123...',
  apiKey: 'hl-...',
})
```

## Development

Scripts:

- `yarn build`
- `yarn start`
- `yarn dev`
- `yarn inspect`
- `yarn test`
- `yarn test:coverage`

## CI/CD

- `.github/workflows/build.yaml`: build + test on PR open/sync
- `.github/workflows/publish.yaml`: build + test + publish on `main` push (markdown-only changes ignored)

## License

MIT