Talunt MCP

Model Context Protocol server for Talunt — agentic lead finding and LinkedIn + email outbound. Plug the full Talunt control plane — search, sequences, leads, message threads, performance metrics, enrichment — into any MCP-compatible AI host. Claude Desktop, Claude Code, Cursor, Windsurf, Zed.

Once installed you can do anything from chat that you'd normally do in the Talunt UI:

Pause my "Cold outbound" sequence — it's sending too fast.

In the third step of "Founder outreach", soften the tone.

Find senior Rust engineers in Berlin and drop them into "Eng outbound."

Search for Twitter founders and add the best leads to a sequence.

Enrich the 30 LinkedIn URLs in leads.txt and tell me which ones work at YC startups.

The AI host picks the right tool, calls Talunt, and writes back the answer.

Requirements

• Node.js 20+
• A Talunt API key (tlnt_…) — create one at https://app.talunt.io/admin/api-keys.
  • Pick the scopes you need (see below).
  • Any non-enrichment scope must be tied to a specific company.

Install — Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "talunt": {
      "command": "npx",
      "args": ["-y", "talunt-mcp"],
      "env": {
        "TALUNT_API_BASE_URL": "https://app.talunt.io",
        "TALUNT_API_KEY": "tlnt_your_key_here"
      }
    }
  }
}

Restart Cursor.

Install — Claude Desktop

Same JSON, file at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Install — Claude Code

claude mcp add talunt -- npx -y talunt-mcp
claude mcp env talunt TALUNT_API_BASE_URL https://app.talunt.io
claude mcp env talunt TALUNT_API_KEY tlnt_your_key_here

Tools

Health & enrichment (global scopes)

| Tool | Scope | |---|---| | talunt_health_check | none | | talunt_enrich_profile | enrich:profile | | talunt_enrich_company | enrich:company |

Sequences (company-scoped)

| Tool | Scope | |---|---| | talunt_list_sequences | sequences:read | | talunt_get_sequence | sequences:read | | talunt_get_sequence_metrics (funnel + reply rate + per-step engagement) | sequences:read | | talunt_create_sequence (supports AI-agent goal/completion/voice step fields) | sequences:write | | talunt_update_sequence (name / description / conversion_goal / personalization_prompt / settings / exclude_previously_enrolled / skip_prior_outreach) | sequences:write | | talunt_add_sequence_step (supports AI-agent goal/completion/voice step fields) | sequences:write | | talunt_delete_sequence_step | sequences:write | | talunt_set_sequence_status (pause/resume/archive/draft) | sequences:write | | talunt_edit_sequence_step (supports AI-agent goal/completion/voice step fields) | sequences:write | | talunt_delete_sequence | sequences:write | | talunt_enroll_leads | sequences:write | | talunt_validate_sequence_flow, talunt_check_prior_outreach | sequences:write, sequences:read | | talunt_list_sequence_enrollments, talunt_get_enrollment_thread, talunt_export_sequence_enrollments | sequences:read | | talunt_list_sequence_personalizations | sequences:read | | talunt_generate_sequence_personalizations, talunt_save_sequence_personalization | sequences:write | | talunt_pause_enrollment, talunt_resume_enrollment, talunt_switch_enrollment_email | sequences:write | | talunt_move_enrollment, talunt_advance_enrollment, talunt_complete_enrollment | sequences:write | | talunt_retry_enrollment, talunt_execute_enrollment_now, talunt_mark_enrollment_connected | sequences:write | | talunt_remove_sequence_enrollments | sequences:write | | talunt_get_company_context | sequences:read | | talunt_update_company_context | sequences:write |

LinkedIn sequence steps use message_type: "message". They default auto_connect_if_not_connected and send_after_connection to true unless either field is explicitly set to false. connection_request, twitter_follow, and wait_for_connection are not message types; wait_for_connection remains available as a trigger_type.

Search helpers (company-scoped)

| Tool | Scope | |---|---| | talunt_list_team_members (resolve send_as_user_id, or run_as_user_id for connection-request batches) | sequences:read |

Leads & messages (company-scoped)

| Tool | Scope | |---|---| | talunt_list_leads | candidates:read | | talunt_get_lead | candidates:read | | talunt_update_lead (mark/archive) | candidates:write | | talunt_get_thread | messages:read | | talunt_send_message (LinkedIn DM / email via connected Gmail or Outlook; requires confirmed: true) | messages:write | | talunt_send_connection_requests (plural; requires confirmed: true) — invite a batch of people in ONE call by name or linkedin_url. Server iterates serially with jitter — NEVER call in parallel or loop client-side. Hard cap 10/call. | messages:write |

Shared inbox (company-scoped)

| Tool | Scope | |---|---| | talunt_list_inbox_accounts, talunt_list_inbox_conversations, talunt_get_inbox_thread | inbox:read | | talunt_mark_inbox_read, talunt_set_inbox_starred, talunt_set_inbox_done | inbox:write | | talunt_draft_inbox_reply (generates copy only; does not send) | inbox:write | | talunt_send_inbox_reply (requires confirmed: true) | inbox:write |

People search (company-scoped)

| Tool | Scope | |---|---| | talunt_search_people — modes: broad (Search Chat Agent pipeline), first_degree, second_degree (via the API-key creator's connected LinkedIn account). New searches return at most 25 initial leads; use fetch-more for additional rows. This tool does not accept run_as_user_id. | search:people | | talunt_get_search_results, talunt_fetch_more_search_results, talunt_prepare_search_export, talunt_export_search_csv — poll/read saved searches, fetch additional provider pages, prep selected rows, and export CSV text. Responses include credit usage for top-ups/enrichment. | search:people | | talunt_enrich_search_phones — enrich verified mobile numbers for saved search rows. Uses the same credit accounting as the UI: 5 lead credits per verified phone, unused reservations released when no phone is found. | search:people | | talunt_hide_search_candidates, talunt_restore_hidden_search_candidates, talunt_set_search_cell, talunt_create_search_column, talunt_get_search_qualification — MCP access to the same search-table actions the UI exposes. | search:people | | talunt_web_search — raw Exa neural web search. Returns URLs and source content without DataForB2B enrichment or a separate Groq fit filter. The default category is people; choose personal site, news, or research paper explicitly for those sources. Supports pagination via resume_search_id. | search:web | | talunt_find_lookalikes — DataForB2B AI lookalike search. Give it one LinkedIn profile URL and get back people with similar backgrounds; results are persisted as leads (each with a lead_id) and recorded in /search history exactly like talunt_search_people. Supports offset pagination. | search:people | | talunt_search_companies — DataForB2B firmographic company search (industry, size, HQ, funding, tech stack). Returns company records for account-based sourcing — not enrollable leads. Chain into talunt_enrich_company or talunt_search_people. | search:companies | | talunt_list_searches | search:people | | talunt_cancel_search, talunt_delete_search (require confirmed: true) | search:people |

CRM (company-scoped)

| Tool | Scope | |---|---| | talunt_list_crm_records, talunt_get_crm_record, talunt_get_crm_meeting_notes | crm:read | | talunt_list_crm_stages, talunt_list_crm_fields, talunt_check_crm_person | crm:read | | talunt_export_crm_records, talunt_export_selected_crm_records | crm:read | | talunt_create_crm_record, talunt_update_crm_record, talunt_add_crm_person | crm:write | | talunt_create_crm_stage, talunt_update_crm_stage, talunt_reorder_crm_stages | crm:write | | talunt_save_crm_fields, talunt_set_crm_field_hidden, talunt_sync_granola_meeting_notes | crm:write |

Outreach and analytics (company-scoped)

| Tool | Scope | |---|---| | talunt_get_outreach_digest_preferences, talunt_get_outreach_unread_count | outreach:read | | talunt_list_outreach_templates | outreach:read | | talunt_list_outreach_recommendations (weekly AI optimization suggestions + generatedAt) | outreach:read | | talunt_execute_outreach_recommendation (apply a saved recommendation by id; requires confirmed: true) | outreach:manage | | talunt_update_outreach_digest_preferences | outreach:manage | | talunt_create_outreach_template, talunt_update_outreach_template, talunt_delete_outreach_template | outreach:manage | | talunt_get_daily_sends, talunt_get_outreach_timeline, talunt_get_outreach_segments, talunt_get_workspace_usage | analytics:read |

Company settings and intelligence (company-scoped)

| Tool | Scope | |---|---| | talunt_get_workspace_settings, talunt_update_workspace_settings | settings:read, settings:write | | talunt_list_sales_icps, talunt_get_website_icp | company:read | | talunt_scrape_company_context, talunt_update_website_icp | company:write |

Integrations & Billing (read-only, company-scoped)

| Tool | Scope | |---|---| | talunt_list_integrations (Gmail plus LinkedIn / Outlook / IMAP messaging status; not ATS or Typeform) | integrations:read | | talunt_list_integration_senders, talunt_get_attio_status, talunt_list_integration_toolkits | integrations:read | | talunt_get_channel_access (per-account team view/edit access matrix for sequences + inbox) | integrations:read | | talunt_get_sender_health | sequences:read or integrations:read | | talunt_get_billing (plan, trial, usage meters, lifetime stats) | billing:read |

Starting or resuming outbound work and destructive operations require confirmed: true. This includes activating a sequence, enrolling leads, and resuming a paused enrollment. The MCP server removes that field before forwarding unless the API route has its own confirmation field. OAuth connect/disconnect flows are intentionally not exposed.

Environment

| Variable | Required | Default | Description | |---|---|---|---| | TALUNT_API_BASE_URL | no | http://localhost:3000 | Origin of your Talunt deployment, no trailing slash. | | TALUNT_API_KEY | yes for everything but health | — | tlnt_… Bearer token. |

Troubleshooting

• Claude Code: talunt can't be enabled, and /mcp enable talunt does nothing — answering no to Claude Code's trust prompt writes talunt into deniedMcpServers. A denied server is dropped from the registry entirely, so /mcp enable reports it as unknown instead of blocked, and Claude can't clear it for you — editing that file is exactly what the permission classifier blocks. Remove it by hand — you are deleting one entry from a list, not the server. Your config, env block, and API key live in ~/.claude.json (or .mcp.json) and are untouched, so there is nothing to reinstall.

  Two things to watch for. Denied lists merge across every settings layer, so check the project files too, not just ~/.claude/settings.json. And entries match on either serverName or serverCommand — an entry that denies npx -y talunt-mcp never contains the string talunt as a name, so read the whole array rather than grepping for our name:

  # print the full denied list from every layer — inspect all of it, not just name matches
  for f in ~/.claude/settings.json .claude/settings.json .claude/settings.local.json; do
    [ -f "$f" ] && echo "--- $f" && python3 -c "import json,sys;print(json.load(open('$f')).get('deniedMcpServers','—'))" "$f"
  done
  # remove any entry naming talunt OR running talunt-mcp, fully restart, then:
  claude mcp list

• Tools don't appear — fully restart the AI host after editing config.

• Missing API key — TALUNT_API_KEY env var isn't being passed to the MCP. Check the env block.

• Missing required scope: … — grant the scope on the key in admin → API Keys.

• Scope … requires a company-scoped key — the key isn't tied to a company. Edit it and pick one.

• Subscription is not active — gated search, campaign, and sequence operations require an active subscription on the company.

Local development

git clone <repo>
cd mcp/talunt-mcp
npm install
npm run build

Point your host at the local build:

{ "mcpServers": { "talunt": {
  "command": "node",
  "args": ["/ABS/PATH/mcp/talunt-mcp/dist/index.js"],
  "env": { "TALUNT_API_BASE_URL": "http://localhost:3000", "TALUNT_API_KEY": "tlnt_..." }
}}}

npm run dev runs tsx watch against src/index.ts for hot reload.

License

MIT