Quick Enrich MCP

NPM package: @mackody/quickenrich-mcp

Standalone MCP server and CLI for Quick Enrich's documented APIs. It is built for internal prospecting workflows: secure local API-key storage, exact person enrichment, reverse-email/phone lookup, domain lead pulls, contact/company finder calls, CSV/JSONL workflows, and compact batch envelopes for agent use.

Docs source: Quick Enrich API Documentation.

License

This package is not open source. It is published under the Quick Enrich MCP Restricted License for controlled internal evaluation only.

Commercial, production, hosted, payment-gated, customer-facing, SaaS, resale, agency, consulting, marketplace, or third-party service integrations require prior written permission from Cody Robertson or an authorized Mackody representative.

Install From NPM

npm install -g @mackody/quickenrich-mcp
quickenrich-token set
quickenrich-token doctor

Requires Node.js 20 or newer.

You can also run without a global install:

npx -p @mackody/quickenrich-mcp quickenrich-token set
npx -y @mackody/quickenrich-mcp

MCP Client Config

Global install config:

{
  "mcpServers": {
    "quick-enrich": {
      "command": "quickenrich-mcp",
      "env": {
        "QUICKENRICH_MCP_TOOL_MODE": "agent",
        "QUICKENRICH_MCP_RESPONSE_MODE": "compact"
      }
    }
  }
}

No-install npx config:

{
  "mcpServers": {
    "quick-enrich": {
      "command": "npx",
      "args": ["-y", "@mackody/quickenrich-mcp"],
      "env": {
        "QUICKENRICH_MCP_TOOL_MODE": "agent",
        "QUICKENRICH_MCP_RESPONSE_MODE": "compact"
      }
    }
  }
}

MCP server alias: quick-enrich

Use QUICKENRICH_MCP_TOOL_MODE=minimal for only auth, graph, natural-language planning, and batch pull. Use QUICKENRICH_MCP_TOOL_MODE=full when you want every low-level endpoint and verbose schema descriptions. Default agent mode is the recommended NPM install mode.

Auth

quickenrich-token set
quickenrich-token status
quickenrich-token doctor

The token CLI stores the key at ~/.config/quickenrich-mcp/config.json with 0600 permissions. Env vars override the config file.

For CI or ephemeral MCP hosts, set:

export QUICKENRICH_API_KEY=...

Agent Project Setup

After installing the package, add the two managed agent hints to a project:

quickenrich-agent-docs install --cwd /path/to/agent-project

quickenrich-agent-docs install appends exactly two Quick Enrich how-to-use lines to CLAUDE.md and AGENTS.md. It is idempotent.

Remove those managed lines with:

quickenrich-agent-docs uninstall --cwd /path/to/agent-project

Package Binaries

• quickenrich-mcp: stdio MCP server.
• quickenrich-token: secure local API-key setup and auth diagnostics.
• quickenrich-agent-docs: install/uninstall agent usage hints in CLAUDE.md and AGENTS.md.

Agent Tool Surface

Default agent tools:

• quickenrich_auth_status
• quickenrich_agent_graph
• quickenrich_natural_language
• quickenrich_pipeline
• quickenrich_batch_pull_leads
• quickenrich_batch_reverse_email
• quickenrich_batch_employee_search
• quickenrich_reverse_email
• quickenrich_lookup_values

Full-mode tools (QUICKENRICH_MCP_TOOL_MODE=full) also expose:

• quickenrich_pipeline
• quickenrich_employee_search
• quickenrich_phone_search
• quickenrich_reverse_email
• quickenrich_batch_reverse_email
• quickenrich_batch_employee_search
• quickenrich_domain_search
• quickenrich_contact_finder
• quickenrich_company_finder
• quickenrich_batch_pull_leads
• quickenrich_lookup_values

Default agent mode intentionally emits slim schemas and short tool descriptions so cold agents do not spend context on prose they can recover from quickenrich_agent_graph. The default tools/list surface is budgeted under 8 KB and includes lookup discovery because finder filters need valid country, industry, employee-range, revenue-range, and service values.

Responses default to compact mode with a 12 KB output budget, 12 array items, 48 object keys, depth 4, and 240-character strings. Pass response: { "mode": "full", "maxOutputChars": 64000 } for rawer output, or response: { "mode": "meta" } for shape-only output.

MCP tool text is emitted as single-line JSON by default to reduce stdio bytes and token overhead. Set QUICKENRICH_MCP_PRETTY_JSON=1 only when debugging by hand.

The API client uses a native keep-alive HTTP transport by default for lower batch overhead. Set QUICKENRICH_API_USE_FETCH=1 to force the global fetch transport while debugging.

Batch Pull

Example MCP arguments:

{
  "companies": [
    { "company_url": "example.com", "title": "Founder" },
    { "company_url": "shop.example", "title": "CEO" }
  ],
  "per_company_limit": 20,
  "pages_per_company": 1,
  "has_email": true,
  "concurrency": 8,
  "requests_per_minute": 300,
  "burst_size": 1,
  "max_credits": 100,
  "export_format": "jsonl",
  "enrich_contacts": false
}

Native batch surfaces:

• quickenrich_pipeline: native company-finder to domain-search workflow with durable output and projected rows.
• quickenrich_batch_pull_leads: domain lead pulls plus Contact Finder and Company Finder batch modes.
• quickenrich_batch_reverse_email: deduped reverse-email lookup from emails, input_csv, or input_jsonl.
• quickenrich_batch_employee_search: exact-person lookup from persons, input_csv, or input_jsonl, with optional phone enrichment.

Batch-native controls:

• max_credits: stops starting new paid calls after the budget is reached. Paid lanes reserve estimated credits before starting work, so they keep safe parallelism without overspending the caller's budget.
• resume_state: skips previously completed or failed keys and returns resumeState with completed, failed, and pending keys for continuing large runs.
• input_file: local CSV/JSONL path or file:// URL for large jobs without pasting rows into prompts.
• output_file: local JSONL/CSV artifact path for results.
• resume_file: local JSON checkpoint merged with resume_state and updated as work completes.
• projection: people, companies, emails, phones, ids, or full for token-efficient row shape.
• cache_mode: off, read, write, readwrite, refresh, or cache_only for local duplicate-spend avoidance.
• credit_ledger: appends a local JSONL credit/request ledger when enabled.
• Finder-mode resumes include a filter fingerprint and nextPage; pass the returned resumeState back unchanged to continue a large Contact Finder or Company Finder run.
• Reverse-email batches locally fail invalid/reserved email domains before calling Quick Enrich.
• validate_filters: validates lookup-backed Contact Finder and Company Finder fields before calling vendor search endpoints.
• requests_per_minute and burst_size: endpoint-specific pacing controls. Env defaults are also supported, e.g. QUICKENRICH_EMPLOYEE_SEARCH_REQUESTS_PER_MINUTE.
• export_format: jsonl or csv; returned inline as export.text.
• input_csv / input_jsonl: native text ingestion for domain-search, reverse-email, and exact-person batch tools.
• response:{mode:"meta"} keeps scalar metrics and collection lengths while omitting records for low-token planning passes.
• max_results: target result count for Contact Finder and Company Finder pagination.
• Finder auto-pagination runs page 1 first to discover last_page, then fans out remaining safe pages up to concurrency. Credit-limited Company Finder fanout is capped by the remaining reserved budget.

Typed finder builders:

{
  "mode": "contact_finder",
  "filters": {
    "company_name": { "include": ["Acme"], "exclude": [] },
    "country_code": ["US"],
    "title": { "include": ["CEO"], "exclude": ["Intern"] }
  },
  "has_email": true,
  "has_phone": true,
  "max_results": 100,
  "per_page": 50
}

Company Finder uses company-shaped output with domain, linkedin_url, services, snippets, firmographics, and contact fields preserved. Supported typed company filters include home_page_text, bio_li, services, industry, number_of_employees, revenue, country_code, city, company_name, and company_url.

Lookup-backed validation covers Contact Finder country_code, industry_linkedin, number_of_employees, and revenue; Company Finder services, industry, country_code, number_of_employees, and revenue. Validation is opt-in because public lookup endpoints are external dependencies; successful lookup reads are cached in-process.

Agent graph:

• quickenrich_agent_graph returns endpointCoverage, agentRouting, budgetMath, lookupHints, inputHints, and envelopePolicy so cold agents can choose native batch tools without reading docs.
• quickenrich_natural_language routes CSV/JSONL reverse-email, exact-person, domain-search, finder, and resume intents to the native batch tools. It returns requires for missing payloads and refuses execute=true when required fields are absent.

Credit/rate notes from the current docs:

• Search, phone, reverse-email: 1000 requests/minute.
• Domain search: 300 requests/minute, up to 20 contacts/page.
• Contact finder and company finder: 120 requests/minute.
• Contact finder is discovery-only and does not return email/phone values; use enrich_contacts: true only when you intentionally want follow-up employee/phone lookups.
• For domain search, use has_email: true when you only want contacts with an email signal. This is useful before paid enrichment and keeps agent envelopes cleaner.

Domain batch pulls use a shared token-bucket limiter per MCP client plus a rolling 60-second cap. The default is Quick Enrich's published requests_per_minute=300 with burst_size=8, so small deduped batches start immediately while sustained traffic still refills at one token every 200 ms without exceeding the rolling minute ceiling. Set burst_size:1 for strict one-at-a-time pacing, or set a higher lane only with provider approval:

QUICKENRICH_DOMAIN_SEARCH_REQUESTS_PER_MINUTE=300 \
QUICKENRICH_DOMAIN_SEARCH_BURST_SIZE=8 \
quickenrich-mcp

The batch result includes throttle metadata showing the active ceiling, burst, total acquired slots, and sleep time. Repeated calls through the same MCP process share buckets, so follow-up batches do not reset the burst. If a final 429 includes Retry-After, the limiter cools down before later starts.

Use throttle_scope:"shared" to coordinate the rolling request ceiling across multiple local MCP processes through a small local file lock. This does not bypass published Quick Enrich limits; it keeps separate agents inside the same ceiling.

Other batch lanes also use small compliant default bursts: employee search, phone search, and reverse email default to burst_size=16; Contact Finder and Company Finder default to burst_size=4.

Source Development

Clone the repo only if you are developing the package itself:

git clone https://github.com/codyrobertson/quickenrich-mcp.git
cd quickenrich-mcp
npm install
npm run smoke

Run the full local plus live suite when a Quick Enrich key is configured:

npm run test

The default suite includes:

• agent docs install/uninstall smoke
• token CLI config and redaction smoke
• offline contract smoke
• mocked Quick Enrich API smoke
• duplicate-request coalescing and concurrency smoke
• native batch capabilities smoke
• resumability and finder-validation ops smoke
• request pacing/rate-limit contract smoke
• shared token-bucket burst contract smoke
• reverse-email high-concurrency floor smoke
• paged finder floor smoke
• serialization floor smoke
• local direct-vs-MCP floor benchmark
• benchmark fixture/comparison contract smoke
• default agent-surface smoke
• compact envelope budget smoke
• cold-agent envelope/workflow smoke
• MCP stdio config smoke
• live Quick Enrich auth smoke when a key is configured
• live native batch no-credit smoke when a key is configured
• live MCP stdio auth smoke when a key is configured

The live auth probes use random reverse-email no-match calls and fail if Quick Enrich reports credits_used > 0.

Observed vendor diagnostic: GET /api/lookups/country-codes returned HTTP 500 during live testing on 2026-07-08. The live smoke records this as a non-blocking diagnostic because the authenticated no-match probe is the real auth gate.

Live Benchmark

npm run bench:live
npm run bench:floor
npm run bench:credit

The default benchmark uses random no-match company domains with a title filter and fails closed if Quick Enrich returns records or reports any credit usage. It compares:

• raw_sequential: direct Quick Enrich API calls for every input row, including duplicates.
• raw_concurrent_deduped: direct Quick Enrich API calls after caller-side dedupe and concurrency.
• direct_core_batch: the local batch tool path without stdio transport.
• mcp_batch_stdio: the real MCP stdio tool path.

Default shape: 2 iterations, 12 input companies per iteration, 6 unique domains, duplicate factor 2, concurrency 8, per_page=5. Override with QUICKENRICH_BENCH_ITERATIONS, QUICKENRICH_BENCH_UNIQUE, QUICKENRICH_BENCH_DUPLICATE_FACTOR, QUICKENRICH_BENCH_CONCURRENCY, and QUICKENRICH_BENCH_PER_PAGE.

Set QUICKENRICH_BENCH_META_LANE=1 to add an extra mcp_batch_stdio_meta diagnostic lane. It is opt-in because shared token buckets make back-to-back lanes intentionally affect each other.

npm run bench:credit sets QUICKENRICH_BENCH_SPEND_CREDITS=1, uses real domains, and requires at least one credit to be spent unless QUICKENRICH_BENCH_REQUIRE_CREDITS=0 is set. Override paid-run domains with QUICKENRICH_BENCH_DOMAINS="example.com,sample.com".

The fair production claim is that MCP batch should beat naive raw sequential API usage by coalescing duplicate work and running the remaining requests concurrently. An already-optimized raw client that dedupes and parallelizes requests can be as fast or faster because it has no JSON-RPC stdio envelope.

npm run bench:floor uses a local mock API and spends no credits. It measures implementation overhead without vendor latency by default; set QUICKENRICH_FLOOR_MOCK_LATENCY_MS to model response latency. Latest local floor run on 2026-07-09:

• reverse_csv_jsonl: direct core 8.71 ms, MCP stdio 7.43 ms, 64 requests, 64 found, 11.1 KB JSONL export.
• exact_csv_phone_csv_export: direct core 6.99 ms, MCP stdio 6.51 ms, 64 requests, 32 found, 4.6 KB CSV export.
• contact_finder_paging_jsonl: direct core 2.30 ms, MCP stdio 1.43 ms, 4 paged requests, 20 leads, 4.5 KB JSONL export.
• company_finder_paging_csv: direct core 1.20 ms, MCP stdio 1.33 ms, 4 paged requests, 20 companies, 2.7 KB CSV export.
• Guardrail: local MCP stdio must stay within 2.5x of direct core for every floor lane.

Latest default token-bucket no-credit local run on 2026-07-09 against https://app.quickenrich.io:

• Shape: 2 iterations, 12 input companies, 6 unique no-match domains, duplicate factor 2, default 300/min with burst 8.
• raw_sequential: 1602.61 ms average, 12 requests/iteration, 0 credits.
• raw_concurrent_deduped: 194.37 ms average, 6 requests/iteration, 0 credits.
• direct_core_batch: 213.22 ms average, 6 requests/iteration, 0 credits.
• mcp_batch_stdio: 241.81 ms average, 6 requests/iteration, 0 credits.
• Result: MCP stdio batch was 6.63x faster than naive raw sequential API usage and cut request volume 2x.

Latest default token-bucket paid local run on 2026-07-09:

• Shape: 1 iteration, danosseasoning.com and sagegoddess.com, duplicate factor 2, default 300/min with burst 8.
• raw_sequential: 666.60 ms, 4 requests, 4 credits, 4 leads.
• raw_concurrent_deduped: 237.11 ms, 2 requests, 2 credits, 2 leads.
• direct_core_batch: 266.64 ms, 2 requests, 2 credits, 2 leads.
• mcp_batch_stdio: 318.64 ms, 2 requests, 2 credits, 2 leads.
• Result: MCP stdio batch was 2.09x faster than naive raw sequential API usage, cut request volume 2x, and saved 50% credits on duplicate inputs.