<p align="center"> <img src="docs/banner.jpg" width="100%" alt="An AI agent at a laptop, streaming results into a stack of contact records beside a database and a magnifier."> </p>

LinkedIn Sales Navigator MCP Server

<!-- mcp-name: io.github.nick-choudhary/linkedin-sales-nav-mcp -->

MCP server that gives AI assistants (Claude Desktop, Claude Code, any MCP client) access to LinkedIn Sales Navigator contact and account search — by driving a real, logged-in browser on your machine and capturing Sales Navigator's own search API responses.

Why this design (and why not cookie-replay)

The common approach — copy your li_at + JSESSIONID cookies and replay them as HTTP requests from a server — gets you logged out repeatedly. LinkedIn scores each session on IP, browser fingerprint, TLS, and the full cookie set; two replayed cookies from a different machine look like a hijacked session, so it invalidates them.

This server does the opposite. It keeps a persistent browser profile you log into once, by hand, and then lets that genuine session do the work:

MCP client (Claude) ──stdio/HTTP──> this server ──drives──> your logged-in Chromium ──> Sales Navigator
                                                    │
                                          captures the JSON the browser
                                          itself receives (page.on "response")

Every request to LinkedIn originates from the real browser: your IP, your fingerprint, your full cookie jar, browser-generated CSRF/track headers, and the session is refreshed by the browser as normal. Nothing is replayed or reconstructed. That is what keeps you signed in.

We never automate the login itself — typing credentials is a strong bot signal. You sign in manually once; the profile persists.

Tools

| Tool | What it does | |------|--------------| | search_contacts | People/lead search from a Sales Navigator URL. Navigates + paginates in the browser, saves records to SQLite, returns a small progress summary. | | search_accounts | Company/account search from a Sales Navigator URL. Same, for accounts. | | enrich_leads | Add Open Profile / InMail status to a saved contact search. Costs one LinkedIn request per lead, so it is opt-in and resumable — see Open Profile status. | | fetch_lead_profiles | Depth 3: full profiles for drafting (~15 KB/lead). Opt-in via ENABLE_PROFILE. | | get_lead_profile | Read one stored full profile. Local only, no LinkedIn call. | | pipeline_status | One funnel view: scraped → enriched → open → profiled → sent. | | reconcile_outreach | Settle sends stuck in sending against LinkedIn itself. | | run_outreach_batch | Draft and send for several leads in one call via MCP sampling. Same guards; dry_run defaults true. | | check_replies | Read the inbox and mark leads who answered. Sends nothing. | | next_outreach_batch | Leads eligible for a first message — Open Profile first, anyone already contacted excluded. Read-only. | | send_message | Send ONE message. The only tool that writes to LinkedIn: off by default, dry_run=true by default. | | outreach_status | Counts by status and channel, plus remaining daily cap. | | check_session_status | Reports whether the browser profile has a live Sales Navigator session (tells you if you need to re-run --login). | | list_queries | Every saved search with its progress: url_hash, status, last_page, records_count. | | get_results | Pull a bounded slice (1–200) of a saved query's records into the conversation for analysis. | | export_results | Write a saved query's records to JSON and/or CSV under the output folder. |

Both search tools take a full Sales Navigator URL (build the search in the UI, copy it from the address bar) and a pages count (1–10, 25 results each).

Beyond tools, the server exposes one resource (sales-nav://queries — saved queries and their progress as attachable JSON context) and one prompt (sales_nav_search_workflow — the step-by-step prospecting playbook, for clients that support MCP prompts).

Search tools do not return the records

This is deliberate, and it is the thing most likely to surprise you. Records go to SQLite; the tool returns only a status object, so a 250-row scrape doesn't dump 250 rows into the model's context:

{
  "url_hash": "a6ca46c9365bce93",
  "scraper_type": "contacts",
  "status": "paused",              // new | in_progress | paused | complete
  "new_records_this_call": 25,
  "total_records": 25,
  "total_available": 11897313,
  "pages_fetched": 1,
  "last_page": 1,
  "next_page": 2,                  // null once exhausted
  "raw_dir": null,                 // set when include_raw=true
  "suggestion": "Saved 25 records so far (through page 1) ..."
}

To get at the data, call get_results (a sample) or export_results (files), or read the SQLite database directly.

Pipeline depth

How far a query is taken is a property of the query, not of the call that made it, so a run resumed tomorrow knows what the search was collected for.

| Depth | Endpoints | Cost per lead | Gate | |---|---|---|---| | search | lead search | one page per 25 | always on | | open_profile | + enrich_leads | ~240 B | ENABLE_ENRICH (default on) | | full | + fetch_lead_profiles | ~15 KB | ENABLE_PROFILE (default off) |

search_contacts(url, pages=4, depth="open_profile")

Depth is stored on the query and echoed back with a next_step. Requesting a depth the server has not enabled is refused with an explanation rather than silently downgraded, so a default install cannot be pointed at a list and made to pull thousands of full profiles.

enrich_leads and fetch_lead_profiles hit the same endpoint with different projections, and stay separate on purpose: the screen runs across a whole list to find who is free to message, the full fetch runs only for the leads you are about to write to. Merging them would pull heavy payloads for leads you never contact — and would make "recent activity" as stale as the screen.

Sending messages

This is the only capability that writes to LinkedIn, and it is treated differently from everything else here. Reading looks like a person browsing; a burst of messages looks like exactly what it is, and the consequence lands on your account rather than on the code. So every default is the cautious one:

| Guard | Default | |---|---| | ENABLE_SENDING | false — a fresh install cannot message anyone | | dry_run | true — returns the exact draft, sends nothing | | ALLOW_CREDIT_SPEND | false — refuses anything that costs an InMail credit | | SEND_DAILY_CAP | 40, rolling 24h, across all campaigns | | SEND_DELAY_MIN/MAX | 45–120s between sends |

Free vs paid, and why enrichment comes first

Open Profile members can be messaged without spending an InMail credit; everyone else costs one from a finite monthly budget. The compose window states which it is — "Free to Open Profile" versus "Use 1 of N credits" — and the sender reads that line, records the channel, and refuses the paid path unless you have explicitly allowed it.

That is why enrich_leads matters commercially and not just as metadata: next_outreach_batch returns only confirmed Open Profile leads by default, so the free channel is the path of least resistance.

Never twice

Outreach state lives in lead_outreach, keyed on (member_id, campaign), and the exclusion is global: anyone with a sent row in any campaign is filtered out of every future batch. Dedupe elsewhere in this server saves a wasted request; here it prevents messaging the same human twice because two searches happened to find them. member_id is the only identifier stable across searches, which is why it is the key.

State is committed per send, never per batch — a crash must not leave a message delivered on LinkedIn but unrecorded here.

The offer file stays yours

The server never generates copy and never learns what you sell. Your positioning lives in a Markdown file that is gitignored and not packaged:

cp offer.example.md offer.md    # then edit it
echo "OFFER_FILE=./offer.md" >> .env

The sales_nav_compose_message prompt renders that file together with the lead record and the drafting rules; your MCP client's model writes the message. With no offer file configured the prompt refuses to render at all.

The evidence gate

The drafting model must return the record fields it drew on:

{"subject": "...", "body": "...", "evidence_used": ["positions[0].title", "companyName"]}

Every entry is resolved against the lead record actually fetched. Name a field that does not exist and the message is rejected unsent. It is a cheap, deterministic check that "personalized" means grounded in data we really have — a message claiming a conference talk gets rejected because nothing supports it. Empty evidence_used is also rejected: that is a template, not personalization.

Unattended batches

Everywhere else the split is deliberate: the server decides who, your client's model decides what to say. That needs a human-driven turn — fine at a desk, useless on a schedule.

run_outreach_batch closes the gap with MCP sampling. The server asks your client for each draft (ctx.sample), so no model runs here, no API key lives here, and no copy is generated by this process — only a request for one.

Nothing is relaxed for automation. Every draft goes through the same send path as a hand-written one: the evidence gate, global dedupe, the daily cap, the free-channel-only default, two-phase commit. dry_run still defaults to true. A draft that fails to parse or fails validation is recorded and skipped rather than sent or allowed to end the run, and the batch stops early when the cap is reached.

run_outreach_batch(url_or_hash, campaign="q3", limit=5)  # drafts only
run_outreach_batch(url_or_hash, campaign="q3", limit=5, dry_run=False)  # sends

The model is given a deliberately narrow slice of the lead — name, title, company, tenure, summary, positions. Not entity_urn, which carries a session token.

Replies

Sending without measuring is not a campaign, and a follow-up to someone who already answered is worse than no follow-up. check_replies reads the Sales Navigator inbox and marks them.

It uses salesApiMessagingThreads, so nothing parses rendered text — a reply is a message whose author is a participant other than you. Two things about that payload are worth knowing, because both were discovered the hard way:

• participantsResolutionResults maps *<urn> to the same <urn> — a reference, not a resolved profile — and included comes back empty. There is no objectUrn and therefore no member_id anywhere in the payload. Matching goes through the profileId embedded in the participant URN, which is the stable part of entity_urn (the authToken after it is search-scoped).
• If the viewer cannot be identified, nothing is classified at all. The dangerous failure is not missing a reply — it is reading your own outbound message as the lead's answer, so it refuses rather than guesses.

Only leads this server recorded a send for are matched; a conversation with someone you messaged by hand is left alone. replied counts as contacted, so a reply can never produce a duplicate first