LinkedIn Sales Navigator

[An AI agent at a laptop, streaming results into a stack of contact records beside a database and a magnifier.]

LinkedIn Sales Navigator MCP Server

[CI] [PyPI] [License: MIT] [MCP Badge]

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

What is code and what is model in a live session. Everything that can be decided from data is decided in code, before any tokens are spent: the ICP screen (FIT_RULES_FILE, applied before a panel is opened, so a rejected lead costs no LinkedIn request either), Open Profile and existing-thread checks, trimming the lead to a fixed budget (summary, current role, three recent posts), and the company block — LinkedIn's own Account IQ dossier boiled down to priorities, challenges, revenue model, workforce and news, or TinyFish news (TINYFISH_API_KEY) when the dossier is empty. The offer is sent once per session, not per lead. The model only writes the message. | 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.

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:

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 itecho "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 onlyrun_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 touch.

The loop

enrich_leads          -> who is free to messagenext_outreach_batch   -> who is eligible, never-contactedget_results           -> the lead's own wordssales_nav_compose_message prompt -> draftsend_message dry_run=true  -> reviewsend_message dry_run=false -> sendcheck_replies         -> who answeredoutreach_status       -> where the campaign stands

Resumable by construction. Stop after ten, come back tomorrow, call next_outreach_batch again and it continues where you left off.

Seniority

Lead search is requested with decoration id com.linkedin.sales.deco.desktop.searchv2.LeadSearchResult-16 rather than the -14 Sales Navigator's own web client asks for. -16 is a strict superset: identical fields plus seniorityV2s, for roughly 230 extra bytes per lead. This is the only place the server alters what the browser asks for, and the rewrite is a no-op on any URL that does not carry a LeadSearchResult id.

seniorityV2s is LinkedIn's own seniority classification, and it is multi-valued — a founder comes back as Owner / Partner + CXO + Senior. The enum is ordered by value:

Records get the whole list under seniorities (sorted most-senior first) plus seniorityTop / seniorityTopId for the single value most callers want. Rows land in a seniorities child table; CSV exports carry seniority_top, seniority_top_id and seniority_summary.

Note it is inferred, not ground truth — "Director of Client Engagement" comes back as Director + Senior. Leads captured before this change simply have no seniority; the columns are blank rather than wrong.

Open Profile status

Sales Navigator's search payload contains an openLink field, and it is a trap: it is false for every lead, premium members included. It is dead decoration. This server therefore does not surface it at all — publishing a column that reads as an authoritative "not Open Profile" for everyone is worse than publishing nothing.

The live flag is memberBadges.openLink, which only the profile endpoint returns — one request per lead. There is no bulk form; salesApiProfiles with an ids=List(...) batch returns 400 in every shape tried. The search endpoint cannot be coaxed into returning it either: it accepts only a registered decorationId, never a free-form projection, and none of the registered IDs (LeadSearchResult-13 … -16) include the field.

So it is a separate, opt-in tool:

enrich_leads(url_or_hash, limit=50, only_missing=true, method="compose")

Two methods:

compose walks the query's results pages row by row. LinkedIn re-ranks between visits, so a lead is taken from whichever visited page it appears on; only leads no longer found fall back to their lead page (via="lead_page" forces that path, which is slower and a real profile view). The panel is only ever closed through its "Close conversation" button; nothing fills a field or touches Send.

Start with a small limit to sample before committing to a whole query. Both are resumable and idempotent — leads already done are skipped, failures stay pending and are retried — so calling repeatedly walks the query to completion. A failed compose capture never overwrites an earlier good result.

Where the data goes. Enrichment is written to its own lead_enrichment table, never into leads.raw_json and never into the normalized records. Two reasons this matters:

• iter_records re-derives every record from raw_json on read, so anything written elsewhere would be silently discarded — and writing it into raw_json would break the "raw is exactly what LinkedIn sent" invariant that normalize.py depends on.
• The table is keyed on member_id, which is stable across searches, rather than entity_urn, which embeds a per-search auth token. A lead found by three different searches is fetched once and shared by all three.

get_results and export_results join it back in: an enrichment block in JSON (with contactInfo and insights lists after a compose capture), and open_profile / inmail_restriction / enriched_at columns in CSV, plus emails / websites / phones / other_contacts / latest_post / job_change / existing_thread_messages / captured_at for captured leads. Contact info and insights live in their own lead_contact_info and lead_insights tables. An empty value means "not checked", which is not the same as false — that distinction is the whole point of keeping the two apart.

One caveat worth knowing: inmailRestriction describes your ability to InMail someone, not their Open Profile status. It reads NO_RESTRICTION for nearly everyone, so do not use it as a proxy.

Searches are resumable. The URL is hashed to a url_hash; calling the same URL again continues from next_page rather than restarting. Sales Navigator caps any single search at 100 pages (2,500 results) no matter what total_available reports — to go past that, split the search into narrower filters and let de-duplication merge the slices.

Browser lifecycle

One Chromium, launched lazily on the first tool call that needs it, and closed either by the lifespan hook on shutdown or by the idle watchdog. There is no per-call launch: relaunching on every call is slow, and repeated launches against the same profile are what risk the session.

Idle timeout. After IDLE_BROWSER_TIMEOUT seconds with no tool call (default 3600 — one hour) the browser closes itself and relaunches on the next call. That reclaims a few hundred MB while you are not scraping, at the cost of a few seconds on the next call, and costs nothing else: your login lives in the profile directory, not in the process. Set it to 0 to keep the browser resident for the whole server lifetime.

The watchdog takes the same lock the tools do, so it can never close a browser mid-operation — a long scrape simply blocks it, and by the time the lock is free the browser is no longer idle.

Orphans. The lifespan hook only runs on a graceful shutdown. If the server is killed, crashes, or its stdio transport drops, Chromium keeps running and keeps holding the profile, and every later launch fails with "Opening in existing browser session" until someone kills it by hand.

The server now recovers from that itself: on a launch failure that looks like a profile lock, it finds the processes holding that exact profile directory, terminates them politely then forcibly, and retries once. The orphan cannot be adopted — patchright launches with --remote-debugging-pipe, so there is no debug endpoint to attach to — but nothing is lost, because the session lives in the profile on disk rather than in the process.

The match requires the resolved profile path to appear literally in a command line and the executable to look like a browser. Your everyday Chrome, other automation browsers, and anything merely mentioning the path are never candidates; when the filter is unsure it matches nothing.

Setup

From PyPI (no clone needed):

uvx --from linkedin-sales-nav-mcp patchright install chromium  # one-time browser download

Or from source:

git clone https://github.com/nick-choudhary/linkedin-sales-nav-mcpcd linkedin-sales-nav-mcpuv syncuv run patchright install chromium   # one-time browser downloadcp .env.example .env                 # optional; defaults are fine on your machine

1. Log in once

uvx linkedin-sales-nav-mcp --login   # PyPI install# or, from a clone: uv run linkedin-sales-nav-mcp --login

A browser window opens. Sign into LinkedIn, open Sales Navigator, finish any 2FA/checkpoint. The server detects the signed-in session and saves the profile, then exits.

2. Run the server

uvx linkedin-sales-nav-mcp             # stdio, PyPI install# or, from a clone: uv run linkedin-sales-nav-mcp

Claude Desktop / Claude Code config

PyPI install:

{  "mcpServers": {    "sales-navigator": {      "command": "uvx",      "args": ["linkedin-sales-nav-mcp"]    }  }}

From a clone:

{  "mcpServers": {    "sales-navigator": {      "command": "uv",      "args": ["run", "--project", "/path/to/linkedin-sales-nav-mcp", "linkedin-sales-nav-mcp"]    }  }}

No secrets in the config — the session lives in the browser profile.

Use --project, not --directory. Both point uv at the repo, but --directory changes the working directory to it, which would send your exports into the repo instead of the project you are working in. --project leaves the working directory alone, which is what the export layout below expects.

Installing it once, for every project

Pointing each config at a repo path gets tedious. Install the command onto your PATH instead:

uv tool install linkedin-sales-nav-mcp   # from PyPI# or: uv tool install /path/to/linkedin-sales-nav-mcp   (from a clone)

Then every project's config is just:

{  "mcpServers": {    "sales-navigator": {      "command": "linkedin-sales-nav-mcp"    }  }}

No path, no flags, and nothing to update when you move the repo. Re-run the install with --force after pulling changes to pick them up.

Either way the database is shared and the login carries over, so a new project needs no --login of its own — only its own .mcp.json entry.

One server at a time

Configure it in as many projects as you like, but only run one at once. The browser profile is a persistent Chromium profile and Chromium takes an exclusive lock on it, so a second server starting while the first is live will fail to launch its browser. If you use uv run, the first server also holds the repo's .venv, and a second uv run can fail while trying to sync it.

Environment variables

Where the data goes

Two directories, because the data has two lifetimes.

State lives in <STATE_DIR> (default ~/.linkedin-sales-nav, beside the browser profile): the SQLite database at sales_nav.db plus any raw captures under <url_hash>/raw/. It belongs to your LinkedIn account rather than to any one project, so it is the same database wherever you launch the server from — list_queries shows one history across every folder.

Exports are project artifacts, so they resolve against the working directory. export_results writes JSON/CSV into <OUTPUT_DIR>/<url_hash>/ (default output/<url_hash>/), landing in whichever project you ran the search for. The database stays the source of truth; exports are generated from it on demand.

Upgrading from 1.0. The database used to live in output/sales_nav.db relative to the launch directory. As of 1.1 it is at ~/.linkedin-sales-nav/sales_nav.db and is no longer read from the old path, so an existing output/sales_nav.db will look empty. Either move it (take sales_nav.db, sales_nav.db-wal, sales_nav.db-shm and the <url_hash>/ directories together — the -wal file holds recent writes), delete it and re-run your searches, or set STATE_DIR=./output to keep the old layout.

Schema version 2 (PRAGMA user_version = 2):

Two things worth knowing:

• raw_json is always stored. LinkedIn's internal API is undocumented and shifts over time, so the complete original element is kept on every row. If the normalizer misses a field, it can be recovered later without re-scraping.
• Records de-duplicate across runs. UNIQUE(url_hash, record_key) plus INSERT OR IGNORE means resuming, re-running, or overlapping searches never create duplicate rows.

Query it with anything that speaks SQLite:

sqlite3 ~/.linkedin-sales-nav/sales_nav.db \  "SELECT full_name, title, company_name FROM leads LIMIT 10;"

Both the database and the exports contain real personal data. output/ is in .gitignore for that reason — keep it that way. <STATE_DIR> sits outside the repo by default, so it is never a commit risk, but it is the copy worth protecting: it accumulates across every project.

Pacing

Pages are not fetched back to back. After each page the server dwells for a random 3–8s before clicking "Next", and every ~5 pages (jittered ±1) it takes a 20–45s break instead. Scroll rhythm is varied too — step count, distance, and the gaps between them.

The reason is cadence, not speed: a page load every two seconds, forever, with no breaks, is a machine signature regardless of how genuine the session is. A full 10-page call therefore takes a couple of minutes, most of it spent deliberately idle. That is working as intended.

Tune with PAGE_DELAY_* / LONG_PAUSE_*, or set PACING_ENABLED=false to disable the delays entirely (not recommended). Raise TOOL_TIMEOUT alongside any large increase.

This lowers your footprint; it does not make you invisible. Volume is what gets accounts flagged, and no jitter setting changes how many profiles you pulled today. Fetch what you need, spread it out, and use an account you own.

Example agent usage

User: Find heads of engineering at mid-size fintech companies in Berlin.

Agent: builds/obtains a Sales Navigator search URL (paste one, or use a URL-builder skill), then:

search_contacts(  search_url="https://www.linkedin.com/sales/search/people?query=(...)",  pages=2)

→ {"url_hash": "a6ca...", "new_records_this_call": 50, "total_records": 50, "next_page": 3, "status": "paused", ...} — the 50 records are now in SQLite, not in the reply.

Agent: then pulls what it needs for the answer:

get_results(url_or_hash="a6ca...", limit=25)      # a sample to reason overexport_results(url_or_hash="a6ca...", format="csv")  # or a file on disk

Important honesty notes

• Field mapping is best-effort. We capture LinkedIn's internal sales-api JSON, which is undocumented and changes over time. The normalizer (sales_nav_mcp/normalize.py) pulls the fields that have been stable. If one looks empty, you have two ways back to ground truth without re-scraping: the raw_json column on every row, or include_raw=true on a search, which writes the complete untouched API responses to <STATE_DIR>/<url_hash>/raw/. Extend the mapper from those. This is the intended maintenance path.
• Pagination selectors for the "Next" control can change; the code tries several fallbacks and stops cleanly if none match. If deep pagination stops early, update _NEXT_SELECTORS in sales_nav_mcp/capture.py.
• Run it on your own machine. A datacenter/cloud IP re-introduces the logout risk this design exists to avoid.
• Scraping LinkedIn is subject to LinkedIn's Terms of Service. Use an account you own, at conservative rates.

Development

uv run pytest          # full unit suite, no browser and no network

Covered: URL validation, JSON normalization against real captured element shapes (with synthetic values), the SQLite store and exports, and pacing — both the delay arithmetic and its wiring into the capture loop, using a fake page and an injected clock so the suite never actually waits.

Not covered: the live browser path. Exercise that by running --login followed by a real search.

Every push and PR runs the same suite plus ruff lint/format checks in CI (Linux on Python 3.12–3.14, Windows and macOS on 3.13), and the release pipeline re-runs the tests before anything is published.

License and who can use this

MIT — see LICENSE. In plain terms: anyone can use, copy, modify, and redistribute this software, commercially or otherwise, free of charge. The only requirement is keeping the copyright and license notice in copies; the software comes with no warranty.

What the license does not cover is your relationship with LinkedIn:

• This project is not affiliated with, endorsed by, or supported by LinkedIn. It automates a browser against LinkedIn's own web application.
• Automated access to LinkedIn is restricted by LinkedIn's Terms of Service. Using this server is your decision and your responsibility — use an account you own, keep volumes conservative, and accept that the account could be restricted.
• The data you collect is real personal data about real people. Handling it may fall under privacy laws such as the GDPR or CCPA depending on where you and the data subjects are. Compliance is on you, not on this tool.