ColdIQ MCP Server

DEPRECATED. This standalone npm package (@coldiq/mcp) is retired. 5.4.23 is its last release: it will never receive another update. From now on, every new ColdIQ tool, fix, and improvement ships only on the hosted ColdIQ MCP: https://mcp.coldiq.com/mcp. It is the only supported and maintained ColdIQ MCP. The code in this folder stays only because the hosted Worker imports the shared instruction core and tool contracts from src/; do not develop new standalone features here.

Move to the hosted MCP. You sign in with your ColdIQ account; no API key. One command replaces this package in Claude Code, Cursor, Codex, Windsurf, and Cline:

curl -fsSL https://raw.githubusercontent.com/Cold-IQ/coldiq-marketplace-skills/main/install.sh | bash

Claude Code by hand: claude mcp remove coldiq, then claude mcp add --transport http --scope user coldiq https://mcp.coldiq.com/mcp, restart, and sign in from /mcp. Setup steps are also in the ColdIQ dashboard: https://coldiq.com/marketplace.

An MCP (Model Context Protocol) server that exposes ColdIQ's B2B data marketplace to AI assistants. Connect it to Claude or any MCP-compatible client to search companies, find and enrich contacts, verify emails, track sales signals, and more — all powered by ColdIQ's unified API.

Prerequisites

• Node.js 18+
• A ColdIQ API key

Configuration

| Variable | Required | Default | Description | |---|---|---|---| | COLDIQ_API_KEY | Yes | — | Your ColdIQ API key | | COLDIQ_API_URL | No | https://api.coldiq.com | Override the API base URL | | COLDIQ_DEBUG | No | — | Set to 1 to enable debug logging | | COLDIQ_HTTP_TIMEOUT_MS | No | 120000 | Per-request timeout. Async verbs (e.g. find_people, bulk jobs) run a full server-side waterfall and can take 20–90s, so the default is deliberately generous. |

Legacy setup (retired package)

The sections below document how existing setups run this retired package. Do not use them for a new install: the install.sh above now installs the hosted MCP, needs no API key, and replaces these npx -y @coldiq/mcp@latest entries.

Connecting to Claude

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "coldiq": {
      "command": "npx",
      "args": ["-y", "@coldiq/mcp@latest"],
      "env": {
        "COLDIQ_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Code

claude mcp add coldiq --scope user --trust -e COLDIQ_API_KEY=<your-key> -- npx -y @coldiq/mcp@latest

The --scope user flag makes the server available in all your projects. The --trust flag skips per-tool approval prompts.

Running directly

COLDIQ_API_KEY=your_key npx @coldiq/mcp@latest

Connecting to other agents

The server is a standard stdio MCP server, so any MCP-compatible client works. Agents without a native skills loader (Codex, Windsurf, Cline) still reach the 18 GTM skills through the list_skills / load_skill tools — installing the MCP is enough.

Cursor

Add to ~/.cursor/mcp.json, then approve the server in Settings → MCP:

{
  "mcpServers": {
    "coldiq": {
      "command": "npx",
      "args": ["-y", "@coldiq/mcp@latest"],
      "env": { "COLDIQ_API_KEY": "your_api_key_here" }
    }
  }
}

Codex

codex mcp add coldiq --env COLDIQ_API_KEY=your_key -- npx -y @coldiq/mcp@latest

Windsurf / Cline

Add the same { "mcpServers": { "coldiq": … } } block (see Cursor) to:

• Windsurf: ~/.codeium/windsurf/mcp_config.json
• Cline: its cline_mcp_settings.json (VS Code globalStorage), then refresh MCP servers.

Available Tools

Prospecting

| Tool | Description | |---|---| | search_companies | Search B2B companies by firmographics, tech stack, funding, headcount, or hiring signals | | find_people | Find people at companies filtered by job title or department | | find_influencers | Discover LinkedIn or Twitter influencers in a niche |

Contact Data

| Tool | Description | |---|---| | find_email | Find a professional email from a name and domain (waterfall across providers) | | verify_email | Check if an email address is deliverable | | find_phone | Find a phone number for a contact |

Enrichment

| Tool | Description | |---|---| | enrich_person | Enrich a person's profile from a LinkedIn URL, name, or domain | | enrich_company | Enrich a company's profile from its domain, LinkedIn URL, or name |

Intelligence & Research

| Tool | Description | |---|---| | find_signals | Surface sales signals: funding rounds, acquisitions, job changes, hiring intent, buying intent, news | | search_jobs | Search live job postings; routes to ATS career sites or LinkedIn based on filters | | search_ads | Discover active LinkedIn ads from a company | | search_seo | SERP rankings, traffic data, and technology stack analysis | | search_reddit | Search Reddit posts and discussions |

Web & Local

| Tool | Description | |---|---| | search_web | General web search (Google or neural/Exa) | | search_places | Find local businesses and places | | fetch_page_content | Extract text content or a summary from any URL |

Development

# Run unit tests
npm test

# Watch mode
npm run test:watch

# Live integration tests (consumes credits)
LIVE_TESTS=1 npm run test:gtm

Tests live in tests/, mirroring the src/ structure. See tests/gtm-scenarios.md for realistic end-to-end usage scenarios.

Architecture

The server is built on three layers:

• Tools (src/tools/) — MCP tool definitions with Zod input schemas and descriptions
• Executor (src/executor.ts) — Waterfall/fallback engine that tries providers in priority order
• Registry (src/registry.ts) — Maps each capability to an ordered list of providers with parameter translation, applicability gates, and response normalization