linkedin-sales-nav-mcp
This server lets AI assistants search LinkedIn Sales Navigator through a real logged-in browser, store and analyze results, and run a guarded, resumable outreach pipeline.
Search contacts and accounts from Sales Navigator URLs, with paging, resume/refresh, and raw JSON capture; results save to SQLite rather than flooding the conversation.
Retrieve and export data — sample records into chat (
get_results), export to JSON/CSV (export_results), and list all saved searches with progress (list_queries).Enrich leads with Open Profile / InMail status, contact info, insights, and existing-thread info (
enrich_leads); fetch full lead profiles for drafting (fetch_lead_profiles,get_lead_profile).Plan and execute outreach — see eligible never-contacted leads (
next_outreach_batch), draft/send one message (send_message), run unattended batches with client-side LLM drafting (run_outreach_batch), and live-session tools (outreach_next,outreach_submit,outreach_skip).Monitor and reconcile — track campaign status and daily caps (
outreach_status), find replies in the inbox (check_replies), resolve ambiguous sends (reconcile_outreach), and see the full pipeline funnel (pipeline_status).Check browser/session health (
check_session_status) so you know when to re-run login.Safety defaults — sending is off by default, dry-run is on, global dedupe, daily caps, InMail-credit spending blocked unless enabled, and evidence-grounded personalization checks.
LinkedIn Sales Navigator MCP Server
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.
Related MCP server: MCP LinkedIn Sales Navigator
Tools
Tool | What it does |
| People/lead search from a Sales Navigator URL. Navigates + paginates in the browser, saves records to SQLite, returns a small progress summary. |
| Company/account search from a Sales Navigator URL. Same, for accounts. |
| Add Open Profile / InMail status to a saved contact search. By default ( |
| Depth 3: full profiles for drafting (~15 KB/lead). Opt-in via |
| Read one stored full profile. Local only, no LinkedIn call. |
| One funnel view: scraped → enriched → open → profiled → sent. |
| Settle sends stuck in |
| Draft and send for several leads in one call via MCP sampling. Same guards; |
| Live session: walks the search results, opens the next eligible lead's message panel from its row, captures it, and returns the lead's data to draft from. Non-Open-Profile leads and existing conversations are skipped automatically. |
| Fills the open panel with the draft. |
| Closes the open panel without sending and records why. |
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.
Depth | Endpoints | Cost per lead | Gate |
| lead search | one page per 25 | always on |
| + | ~240 B |
|
| + | ~15 KB |
|
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 |
|
|
|
|
|
|
| 40, rolling 24h, across all campaigns |
| 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" >> .envThe 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) # sendsThe 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:
participantsResolutionResultsmaps*<urn>to the same<urn>— a reference, not a resolved profile — andincludedcomes back empty. There is noobjectUrnand therefore no member_id anywhere in the payload. Matching goes through the profileId embedded in the participant URN, which is the stable part ofentity_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 message
next_outreach_batch -> who is eligible, never-contacted
get_results -> the lead's own words
sales_nav_compose_message prompt -> draft
send_message dry_run=true -> review
send_message dry_run=false -> send
check_replies -> who answered
outreach_status -> where the campaign standsResumable 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:
id | Level | id | Level |
320 | Owner / Partner | 210 | Experienced Manager |
310 | CXO | 200 | Entry Level Manager |
300 | Vice President | 130 | Strategic |
220 | Director | 120 | Senior |
110 | Entry Level | 100 | In Training |
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:
| What it does | Gets | Speed |
| Clicks Message on each lead's row in the search results, records what the panel loads, closes it. Issues no request of its own and loads no lead page. | Open Profile status, contact info (emails, websites, phones, handles), insights (recent posts and articles, job change, shared connections), existing conversation size, company dossier (raw) | ~2 s capture + pacing pauses (~11 s/lead measured) |
| One trimmed profile request per lead from inside the page | Open Profile status only | ~1 s/lead |
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_recordsre-derives every record fromraw_jsonon read, so anything written elsewhere would be silently discarded — and writing it intoraw_jsonwould break the "raw is exactly what LinkedIn sent" invariant thatnormalize.pydepends on.The table is keyed on
member_id, which is stable across searches, rather thanentity_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 downloadOr from source:
git clone https://github.com/nick-choudhary/linkedin-sales-nav-mcp
cd linkedin-sales-nav-mcp
uv sync
uv run patchright install chromium # one-time browser download
cp .env.example .env # optional; defaults are fine on your machine1. Log in once
uvx linkedin-sales-nav-mcp --login # PyPI install
# or, from a clone: uv run linkedin-sales-nav-mcp --loginA 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-mcpClaude 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
Variable | Default | Purpose |
|
| Persistent browser profile |
|
|
|
| — | Use your own Chrome instead of bundled Chromium |
| — | Leave empty on your own machine; only for a residential exit node if remote |
|
| Close the browser after this many idle seconds; relaunches on demand. |
|
| Timeouts (s) |
|
| Per-tool MCP timeout (s) — must exceed the pacing budget below |
|
| Human-like delays between pages (see below) |
|
| Random dwell before advancing a page (s) |
|
| Take a longer break every N pages ( |
|
| Length of that break (s) |
|
| Where |
|
| Where JSON/CSV exports are written, relative to where the server runs |
|
| Transport |
|
|
|
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.dbrelative to the launch directory. As of 1.1 it is at~/.linkedin-sales-nav/sales_nav.dband is no longer read from the old path, so an existingoutput/sales_nav.dbwill look empty. Either move it (takesales_nav.db,sales_nav.db-wal,sales_nav.db-shmand the<url_hash>/directories together — the-walfile holds recent writes), delete it and re-run your searches, or setSTATE_DIR=./outputto keep the old layout.
Schema version 2 (PRAGMA user_version = 2):
Table | Holds |
| One row per search URL: |
| People (34 columns): name parts, |
| Companies (16 columns): |
| One row per current position, so a lead holding two concurrent roles gets two rows. Search responses do not carry past employment, so it isn't stored |
| Lead/account highlight badges (shared connections, "recently changed jobs", etc.) |
Two things worth knowing:
raw_jsonis 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)plusINSERT OR IGNOREmeans 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 over export_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: theraw_jsoncolumn on every row, orinclude_raw=trueon 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_SELECTORSinsales_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 networkCovered: 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.
Available Tools
16 toolscheck_repliesCheck For RepliesAIdempotent
Read the Sales Navigator inbox and mark leads who replied.
Sends nothing. Reads structured message threads — a reply is a message whose author is the lead rather than you, matched to leads by the stable member_id, so nothing depends on parsing rendered text or guessing who spoke last.
Only leads this server recorded a send for are considered; a
conversation with someone you messaged by hand elsewhere is left alone.
A lead marked replied still counts as contacted, so a reply can never
cause a duplicate first touch.
Inputs: scrolls, campaign. Returns: object
check_session_statusCheck Session StatusARead-only
Check whether the browser profile has a live Sales Navigator session.
Launches (or reuses) the browser and verifies it lands on a signed-in
/sales page. Use this first when searches fail — it tells you if you
need to run --login again.
Returns: Dict with logged_in (bool), plus the profile directory and headless setting for this server.
Inputs: no named parameters. Returns: object
enrich_leadsEnrich Leads With Open Profile StatusARead-only
Add Open Profile / InMail status to a saved contact search.
Search results cannot carry this. Sales Navigator's search payload has
an openLink field, but it is false for everyone — the real flag is
memberBadges.openLink, which only the profile endpoint returns, one
request per lead. There is no bulk endpoint.
Costs one LinkedIn request per lead (~1s each with pacing), so it is a
separate opt-in tool rather than part of search_contacts. Start with
a limit to sample before committing to a whole query.
Results go to the lead_enrichment table, keyed on the stable
member_id, and are joined in by get_results / export_results as
an enrichment block. Search records are never modified, and a lead
enriched once is reused by every search that finds them again.
Resumable and idempotent: with only_missing=true (the default),
leads that already have a successful fetch are skipped, so calling
repeatedly walks through the query. Failed fetches stay pending and
are retried.
Inputs: url_or_hash (required), limit, only_missing. Returns: object
export_resultsExport ResultsBRead-only
Export a saved query's records to files under the output folder.
Inputs: url_or_hash (required), format, include_raw. Returns: object
fetch_lead_profilesFetch Full Lead ProfilesARead-only
Fetch full profiles for a query's leads — depth 3, drafting material.
Same endpoint as enrich_leads, much wider projection: headline,
summary, full position descriptions, educations, skills, languages,
volunteering, connection counts. About 15 KB per lead against ~240
bytes for the enrichment screen.
Deliberately separate from enrich_leads. The screen runs across a
whole list to find who is free to message; this 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.
Requires ENABLE_PROFILE=true — it costs one heavy request per lead,
so a default install will not do it.
Resumable: leads with a successful fetch are skipped, so calling repeatedly walks the query.
Inputs: url_or_hash (required), limit. Returns: object
get_lead_profileGet Lead ProfileARead-only
Read one stored full profile — the payload you draft a message from.
Reads from the local store only; it does not call LinkedIn. Run
fetch_lead_profiles first for leads that have not been fetched.
Inputs: member_id (required). Returns: object
get_resultsGet Results SampleARead-only
Pull a bounded slice of a saved query's records into the conversation for analysis. Bounded on purpose — for large sets, prefer export_results and analyze the file with code rather than loading everything into context.
Inputs: url_or_hash (required), limit, offset. Returns: object
list_queriesList Saved QueriesARead-only
List every saved search and its progress.
Returns:
Dict with queries: for each, url_hash, url, scraper_type, status
(new|in_progress|paused|complete), last_page, total_available,
records_count. Use a url_hash with export_results or get_results.
Inputs: no named parameters. Returns: object
next_outreach_batchNext Outreach BatchARead-only
Leads eligible for a first message, best channel first.
Read-only. Excludes anyone already sent to in ANY campaign — dedupe is on the stable member_id, so a person found by three searches is messaged once — and anyone already handled in this campaign.
With open_profile_only (the default) only leads confirmed Open Profile by enrich_leads come back: those are free to message. Run enrich_leads first or this returns nothing.
Inputs: campaign (required), url_or_hash (required), limit, open_profile_only. Returns: object
outreach_statusOutreach StatusBRead-only
Counts by status and channel, plus remaining daily cap.
Inputs: campaign. Returns: object
pipeline_statusPipeline StatusARead-only
One funnel view of a query: scraped → enriched → open → profiled → sent.
State otherwise lives across four tables; this joins it so "where is everything?" is one call instead of mental arithmetic.
Inputs: url_or_hash (required). Returns: object
reconcile_outreachReconcile Ambiguous SendsAIdempotent
Settle sends stuck in sending by checking LinkedIn itself.
A sending row means the Send click happened but the outcome was never
recorded — a crash, a killed browser, a disconnect. The message either
went out or it did not, and only LinkedIn knows. This opens each lead's
conversation, looks for our own message text, and resolves the row to
sent or failed.
Sends nothing. Until reconciled, an ambiguous lead is treated as already-contacted, so the uncertainty can never produce a duplicate — it can only delay a legitimate follow-up.
Inputs: limit, campaign. Returns: object
run_outreach_batchRun Outreach BatchADestructive
Draft and send for several leads in one call, unattended.
Uses MCP sampling: the server asks YOUR client for each draft, so no model runs here and no API key lives here — only the request for a completion. That is what lets a scheduled job run the loop without a person taking a turn.
Nothing is relaxed for automation. Every draft goes through the same
send path as a manual one: the evidence gate, global dedupe, the daily
cap, the free-channel-only default, and two-phase commit. dry_run
still defaults to true, so the first call shows you what it would say
and sends nothing.
Stops early when the daily cap is reached. A draft that fails to parse or fails validation is recorded and skipped rather than ending the run.
Inputs: campaign (required), url_or_hash (required), limit, dry_run. Returns: object
search_accountsSearch Sales Navigator AccountsARead-only
Search companies/accounts by driving Sales Navigator in the logged-in browser and capturing its search API responses. Results are saved to the local database automatically; this tool returns a small summary, not the records (call export_results or get_results for the data).
Build the search in Sales Navigator (industry / headcount / geography / growth filters), copy the URL from the address bar, and pass it here. Saved account lists work too.
Resumable: the search URL is hashed to a query id. If a previous run stopped partway, calling again with the same URL resumes from the next page instead of restarting.
Inputs: search_url (required), pages, resume, refresh, +1 more. Returns: object
search_contactsSearch Sales Navigator ContactsARead-only
Search people/leads by driving Sales Navigator in the logged-in browser and capturing its search API responses. Results are saved to the local database automatically; this tool returns a small summary, not the records (call export_results or get_results for the data).
Build the search in Sales Navigator (title / geography / industry / seniority / keyword filters), copy the URL from the address bar, and pass it here. Saved lead lists work too.
Resumable: the search URL is hashed to a query id. If a previous run stopped partway, calling again with the same URL resumes from the next page instead of restarting — safe to call repeatedly to page deeper.
Inputs: search_url (required), depth, pages, resume, +2 more. Returns: object
send_messageSend Sales Navigator MessageADestructive
Send ONE Sales Navigator message. Writes to LinkedIn.
This is the only tool here that is not read-only, and it is guarded accordingly:
dry_rundefaults to true — you get back exactly what would be sent and nothing leaves the browser. Set it false deliberately.Sending must also be enabled server-side (
ENABLE_SENDING=true), so a default install cannot message anyone.A lead already messaged in ANY campaign is refused.
A rolling 24h cap applies across all campaigns.
If the lead is not Open Profile the message would spend an InMail credit, and that is refused unless
ALLOW_CREDIT_SPEND=true.evidence_usedmust name fields that exist on the stored lead record, or the draft is rejected as ungrounded.
Inputs: body (required), subject (required), campaign (required), member_id (required), +3 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Most tools target clearly distinct functions: search, results retrieval, enrichment, messaging, and monitoring are well separated. A few pairs like fetch_lead_profiles/get_lead_profile and enrich_leads/fetch_lead_profiles require reading descriptions to avoid confusion, but the detailed docs resolve the boundaries.
Names are consistently snake_case and mostly follow a verb_noun pattern (search_contacts, export_results, send_message, check_replies). A few noun-style names like outreach_status, next_outreach_batch, and pipeline_status break the pattern, but the overall style remains predictable and readable.
At 16 tools, the set is slightly above the ideal range but still justified by the end-to-end Sales Navigator workflow: search, storage, enrichment, messaging, reconciliation, and pipeline visibility. Each tool serves a distinct need, though the count feels a bit heavy for a single server.
The core lifecycle is well covered: search leads/accounts, retrieve and export results, enrich, profile, select, draft, send, reconcile, and check replies. Notable gaps are the lack of a follow-up send path (only first messages appear supported) and no explicit campaign or query lifecycle management tools.
Maintenance
Related MCP Connectors
Give AI agents the LinkedIn tools to find, qualify, engage, and follow up with prospects.
LinkedIn for AI agents: inbox, invitations, Sales Navigator search, posts, jobs, quotas, webhooks.
Live LinkedIn data for AI agents: profiles, companies, jobs, posts, email finding. No account risk.
LinkedIn for AI agents: search people, read profiles, posts and connections via a connected account
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables AI assistants to interact with LinkedIn by scraping profiles, companies, job postings, and getting personalized job recommendations using authenticated browser automation.1711,806 PyPI4,271Apache 2.0
- AlicenseAqualityBmaintenanceEnables AI assistants to search leads, view profiles, manage lists, send InMails, and export data from LinkedIn Sales Navigator through browser automation.817MIT
- AlicenseAqualityDmaintenanceConnects LinkedIn to AI assistants, enabling lead search, profile analysis, messaging, and workflow automation through a cloud browser. Supports sales, recruiting, and market research tasks.59MIT
- AlicenseAqualityCmaintenanceEnables AI assistants to search leads, view profiles, manage lists, send InMails, and export data by automating LinkedIn Sales Navigator through a logged-in browser session.7MIT