\n\n# LinkedIn Sales Navigator MCP Server\n\n[](https://github.com/nick-choudhary/linkedin-sales-nav-mcp/actions/workflows/ci.yml)\n[](https://pypi.org/project/linkedin-sales-nav-mcp/)\n[](LICENSE)\n[](https://lobehub.com/mcp/nick-choudhary-linkedin-sales-nav-mcp)\n\n\n\nMCP server that gives AI assistants (Claude Desktop, Claude Code, any MCP\nclient) access to **LinkedIn Sales Navigator contact and account search** —\nby driving a **real, logged-in browser on your machine** and capturing Sales\nNavigator's own search API responses.\n\n## Why this design (and why not cookie-replay)\n\nThe common approach — copy your `li_at` + `JSESSIONID` cookies and replay them\nas HTTP requests from a server — gets you **logged out repeatedly**. LinkedIn\nscores each session on IP, browser fingerprint, TLS, and the full cookie set;\ntwo replayed cookies from a different machine look like a hijacked session, so\nit invalidates them.\n\nThis server does the opposite. It keeps a persistent browser profile you log\ninto **once, by hand**, and then lets that genuine session do the work:\n\n```\nMCP client (Claude) ──stdio/HTTP──> this server ──drives──> your logged-in Chromium ──> Sales Navigator\n │\n captures the JSON the browser\n itself receives (page.on \"response\")\n```\n\nEvery request to LinkedIn originates from the real browser: your IP, your\nfingerprint, your full cookie jar, browser-generated CSRF/track headers, and\nthe session is refreshed by the browser as normal. Nothing is replayed or\nreconstructed. That is what keeps you signed in.\n\nWe **never** automate the login itself — typing credentials is a strong bot\nsignal. You sign in manually once; the profile persists.\n\n## Tools\n\n| Tool | What it does |\n|------|--------------|\n| `search_contacts` | People/lead search from a Sales Navigator URL. Navigates + paginates in the browser, saves records to SQLite, returns a small progress summary. |\n| `search_accounts` | Company/account search from a Sales Navigator URL. Same, for accounts. |\n| `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](#open-profile-status). |\n| `fetch_lead_profiles` | Depth 3: full profiles for drafting (~15 KB/lead). Opt-in via `ENABLE_PROFILE`. |\n| `get_lead_profile` | Read one stored full profile. Local only, no LinkedIn call. |\n| `pipeline_status` | One funnel view: scraped → enriched → open → profiled → sent. |\n| `reconcile_outreach` | Settle sends stuck in `sending` against LinkedIn itself. |\n| `run_outreach_batch` | Draft and send for several leads in one call via MCP sampling. Same guards; `dry_run` defaults true. |\n| `check_replies` | Read the inbox and mark leads who answered. Sends nothing. |\n| `next_outreach_batch` | Leads eligible for a first message — Open Profile first, anyone already contacted excluded. Read-only. |\n| `send_message` | Send ONE message. The only tool that writes to LinkedIn: off by default, `dry_run=true` by default. |\n| `outreach_status` | Counts by status and channel, plus remaining daily cap. |\n| `check_session_status` | Reports whether the browser profile has a live Sales Navigator session (tells you if you need to re-run `--login`). |\n| `list_queries` | Every saved search with its progress: `url_hash`, status, `last_page`, `records_count`. |\n| `get_results` | Pull a bounded slice (1–200) of a saved query's records into the conversation for analysis. |\n| `export_results` | Write a saved query's records to JSON and/or CSV under the output folder. |\n\nBoth search tools take a **full Sales Navigator URL** (build the search in the\nUI, copy it from the address bar) and a `pages` count (1–10, 25 results each).\n\nBeyond tools, the server exposes one **resource** (`sales-nav://queries` —\nsaved queries and their progress as attachable JSON context) and one\n**prompt** (`sales_nav_search_workflow` — the step-by-step prospecting\nplaybook, for clients that support MCP prompts).\n\n### Search tools do not return the records\n\nThis is deliberate, and it is the thing most likely to surprise you. Records go\nto SQLite; the tool returns only a status object, so a 250-row scrape doesn't\ndump 250 rows into the model's context:\n\n```jsonc\n{\n \"url_hash\": \"a6ca46c9365bce93\",\n \"scraper_type\": \"contacts\",\n \"status\": \"paused\", // new | in_progress | paused | complete\n \"new_records_this_call\": 25,\n \"total_records\": 25,\n \"total_available\": 11897313,\n \"pages_fetched\": 1,\n \"last_page\": 1,\n \"next_page\": 2, // null once exhausted\n \"raw_dir\": null, // set when include_raw=true\n \"suggestion\": \"Saved 25 records so far (through page 1) ...\"\n}\n```\n\nTo get at the data, call `get_results` (a sample) or `export_results` (files),\nor read the SQLite database directly.\n\n## Pipeline depth\n\nHow far a query is taken is a property of the query, not of the call that made\nit, so a run resumed tomorrow knows what the search was collected for.\n\n| Depth | Endpoints | Cost per lead | Gate |\n|---|---|---|---|\n| `search` | lead search | one page per 25 | always on |\n| `open_profile` | + `enrich_leads` | ~240 B | `ENABLE_ENRICH` (default on) |\n| `full` | + `fetch_lead_profiles` | ~15 KB | `ENABLE_PROFILE` (default **off**) |\n\n```python\nsearch_contacts(url, pages=4, depth=\"open_profile\")\n```\n\nDepth is stored on the query and echoed back with a `next_step`. Requesting a\ndepth the server has not enabled is refused with an explanation rather than\nsilently downgraded, so a default install cannot be pointed at a list and made\nto pull thousands of full profiles.\n\n`enrich_leads` and `fetch_lead_profiles` hit the *same* endpoint with different\nprojections, and stay separate on purpose: the screen runs across a whole list\nto find who is free to message, the full fetch runs only for the leads you are\nabout to write to. Merging them would pull heavy payloads for leads you never\ncontact — and would make \"recent activity\" as stale as the screen.\n\n## Sending messages\n\nThis is the only capability that **writes** to LinkedIn, and it is treated\ndifferently from everything else here. Reading looks like a person browsing;\na burst of messages looks like exactly what it is, and the consequence lands on\nyour account rather than on the code. So every default is the cautious one:\n\n| Guard | Default |\n|---|---|\n| `ENABLE_SENDING` | `false` — a fresh install cannot message anyone |\n| `dry_run` | `true` — returns the exact draft, sends nothing |\n| `ALLOW_CREDIT_SPEND` | `false` — refuses anything that costs an InMail credit |\n| `SEND_DAILY_CAP` | 40, rolling 24h, across **all** campaigns |\n| `SEND_DELAY_MIN/MAX` | 45–120s between sends |\n\n### Free vs paid, and why enrichment comes first\n\nOpen Profile members can be messaged **without spending an InMail credit**;\neveryone else costs one from a finite monthly budget. The compose window states\nwhich it is — `\"Free to Open Profile\"` versus `\"Use 1 of N credits\"` — and the\nsender reads that line, records the channel, and refuses the paid path unless\nyou have explicitly allowed it.\n\nThat is why `enrich_leads` matters commercially and not just as metadata:\n`next_outreach_batch` returns only confirmed Open Profile leads by default, so\nthe free channel is the path of least resistance.\n\n### Never twice\n\nOutreach state lives in `lead_outreach`, keyed on `(member_id, campaign)`, and\nthe exclusion is **global**: anyone with a `sent` row in *any* campaign is\nfiltered out of every future batch. Dedupe elsewhere in this server saves a\nwasted request; here it prevents messaging the same human twice because two\nsearches happened to find them. `member_id` is the only identifier stable\nacross searches, which is why it is the key.\n\nState is committed per send, never per batch — a crash must not leave a message\ndelivered on LinkedIn but unrecorded here.\n\n### The offer file stays yours\n\nThe server never generates copy and never learns what you sell. Your\npositioning lives in a Markdown file that is gitignored and not packaged:\n\n```bash\ncp offer.example.md offer.md # then edit it\necho \"OFFER_FILE=./offer.md\" >> .env\n```\n\nThe `sales_nav_compose_message` prompt renders that file together with the lead\nrecord and the drafting rules; your MCP client's model writes the message. With\nno offer file configured the prompt refuses to render at all.\n\n### The evidence gate\n\nThe drafting model must return the record fields it drew on:\n\n```json\n{\"subject\": \"...\", \"body\": \"...\", \"evidence_used\": [\"positions[0].title\", \"companyName\"]}\n```\n\nEvery entry is resolved against the lead record actually fetched. Name a field\nthat does not exist and the message is rejected **unsent**. It is a cheap,\ndeterministic check that \"personalized\" means grounded in data we really have —\na message claiming a conference talk gets rejected because nothing supports it.\nEmpty `evidence_used` is also rejected: that is a template, not personalization.\n\n### Unattended batches\n\nEverywhere else the split is deliberate: the server decides *who*, your client's\nmodel decides *what to say*. That needs a human-driven turn — fine at a desk,\nuseless on a schedule.\n\n`run_outreach_batch` closes the gap with MCP sampling. The server asks **your\nclient** for each draft (`ctx.sample`), so no model runs here, no API key lives\nhere, and no copy is generated by this process — only a request for one.\n\nNothing is relaxed for automation. Every draft goes through the same send path\nas a hand-written one: the evidence gate, global dedupe, the daily cap, the\nfree-channel-only default, two-phase commit. `dry_run` still defaults to true.\nA draft that fails to parse or fails validation is recorded and skipped rather\nthan sent or allowed to end the run, and the batch stops early when the cap is\nreached.\n\n```python\nrun_outreach_batch(url_or_hash, campaign=\"q3\", limit=5) # drafts only\nrun_outreach_batch(url_or_hash, campaign=\"q3\", limit=5, dry_run=False) # sends\n```\n\nThe model is given a deliberately narrow slice of the lead — name, title,\ncompany, tenure, summary, positions. Not `entity_urn`, which carries a session\ntoken.\n\n### Replies\n\nSending without measuring is not a campaign, and a follow-up to someone who\nalready answered is worse than no follow-up. `check_replies` reads the\nSales Navigator inbox and marks them.\n\nIt uses `salesApiMessagingThreads`, so nothing parses rendered text — a reply\nis a message whose `author` is a participant other than you. Two things about\nthat payload are worth knowing, because both were discovered the hard way:\n\n* `participantsResolutionResults` maps `*` to the same `` — a\n reference, not a resolved profile — and `included` comes back empty. There is\n no `objectUrn` and therefore **no member_id anywhere in the payload**.\n Matching goes through the profileId embedded in the participant URN, which is\n the stable part of `entity_urn` (the authToken after it is search-scoped).\n* If the viewer cannot be identified, nothing is classified at all. The\n dangerous failure is not missing a reply — it is reading your own outbound\n message as the lead's answer, so it refuses rather than guesses.\n\nOnly leads this server recorded a send for are matched; a conversation with\nsomeone you messaged by hand is left alone. `replied` counts as contacted, so a\nreply can never produce a duplicate first touch.\n\n### The loop\n\n```\nenrich_leads -> who is free to message\nnext_outreach_batch -> who is eligible, never-contacted\nget_results -> the lead's own words\nsales_nav_compose_message prompt -> draft\nsend_message dry_run=true -> review\nsend_message dry_run=false -> send\ncheck_replies -> who answered\noutreach_status -> where the campaign stands\n```\n\nResumable by construction. Stop after ten, come back tomorrow, call\n`next_outreach_batch` again and it continues where you left off.\n\n## Seniority\n\nLead search is requested with decoration id\n`com.linkedin.sales.deco.desktop.searchv2.LeadSearchResult-16` rather than the\n`-14` Sales Navigator's own web client asks for. `-16` is a strict superset:\nidentical fields plus `seniorityV2s`, for roughly 230 extra bytes per lead.\nThis is the only place the server alters what the browser asks for, and the\nrewrite is a no-op on any URL that does not carry a `LeadSearchResult` id.\n\n`seniorityV2s` is LinkedIn's own seniority classification, and it is\n**multi-valued** — a founder comes back as Owner / Partner + CXO + Senior. The\nenum is ordered by value:\n\n| id | Level | id | Level |\n|---|---|---|---|\n| 320 | Owner / Partner | 210 | Experienced Manager |\n| 310 | CXO | 200 | Entry Level Manager |\n| 300 | Vice President | 130 | Strategic |\n| 220 | Director | 120 | Senior |\n| 110 | Entry Level | 100 | In Training |\n\nRecords get the whole list under `seniorities` (sorted most-senior first) plus\n`seniorityTop` / `seniorityTopId` for the single value most callers want. Rows\nland in a `seniorities` child table; CSV exports carry `seniority_top`,\n`seniority_top_id` and `seniority_summary`.\n\nNote it is inferred, not ground truth — \"Director of Client Engagement\" comes\nback as Director + Senior. Leads captured before this change simply have no\nseniority; the columns are blank rather than wrong.\n\n## Open Profile status\n\nSales Navigator's search payload contains an `openLink` field, and it is a\ntrap: it is `false` for **every** lead, premium members included. It is dead\ndecoration. This server therefore does not surface it at all — publishing a\ncolumn that reads as an authoritative \"not Open Profile\" for everyone is worse\nthan publishing nothing.\n\nThe live flag is `memberBadges.openLink`, which only the profile endpoint\nreturns — one request per lead. There is no bulk form; `salesApiProfiles` with\nan `ids=List(...)` batch returns 400 in every shape tried. The search endpoint\ncannot be coaxed into returning it either: it accepts only a registered\n`decorationId`, never a free-form projection, and none of the registered IDs\n(`LeadSearchResult-13` … `-16`) include the field.\n\nSo it is a separate, opt-in tool:\n\n```\nenrich_leads(url_or_hash, limit=50, only_missing=true)\n```\n\nRoughly one second per lead with pacing. Start with a small `limit` to sample\nbefore committing to a whole query. It is resumable and idempotent — leads that\nalready succeeded are skipped, failures stay pending and are retried — so\ncalling it repeatedly walks the query to completion.\n\n**Where the data goes.** Enrichment is written to its own `lead_enrichment`\ntable, never into `leads.raw_json` and never into the normalized records. Two\nreasons this matters:\n\n* `iter_records` re-derives every record from `raw_json` on read, so anything\n written elsewhere would be silently discarded — and writing it *into*\n `raw_json` would break the \"raw is exactly what LinkedIn sent\" invariant that\n `normalize.py` depends on.\n* The table is keyed on `member_id`, which is stable across searches, rather\n than `entity_urn`, which embeds a per-search auth token. A lead found by\n three different searches is fetched once and shared by all three.\n\n`get_results` and `export_results` join it back in: an `enrichment` block in\nJSON, and `open_profile` / `inmail_restriction` / `enriched_at` columns in CSV.\n**An empty value means \"not checked\", which is not the same as `false`** — that\ndistinction is the whole point of keeping the two apart.\n\nOne caveat worth knowing: `inmailRestriction` describes *your* ability to InMail\nsomeone, not their Open Profile status. It reads `NO_RESTRICTION` for nearly\neveryone, so do not use it as a proxy.\n\n**Searches are resumable.** The URL is hashed to a `url_hash`; calling the same\nURL again continues from `next_page` rather than restarting. Sales Navigator\ncaps any single search at 100 pages (2,500 results) no matter what\n`total_available` reports — to go past that, split the search into narrower\nfilters and let de-duplication merge the slices.\n\n## Browser lifecycle\n\nOne Chromium, launched lazily on the first tool call that needs it, and closed\neither by the lifespan hook on shutdown or by the idle watchdog. There is no\nper-call launch: relaunching on every call is slow, and repeated launches\nagainst the same profile are what risk the session.\n\n**Idle timeout.** After `IDLE_BROWSER_TIMEOUT` seconds with no tool call\n(default 3600 — one hour) the browser closes itself and relaunches on the next\ncall. That reclaims a few hundred MB while you are not scraping, at the cost of\na few seconds on the next call, and costs nothing else: your login lives in the\nprofile directory, not in the process. Set it to 0 to keep the browser resident\nfor the whole server lifetime.\n\nThe watchdog takes the same lock the tools do, so it can never close a browser\nmid-operation — a long scrape simply blocks it, and by the time the lock is free\nthe browser is no longer idle.\n\n**Orphans.** The lifespan hook only runs on a graceful shutdown. If the server\nis killed, crashes, or its stdio transport drops, Chromium keeps running and\nkeeps holding the profile, and every later launch fails with *\"Opening in\nexisting browser session\"* until someone kills it by hand.\n\nThe server now recovers from that itself: on a launch failure that looks like a\nprofile lock, it finds the processes holding **that exact profile directory**,\nterminates them politely then forcibly, and retries once. The orphan cannot be\nadopted — patchright launches with `--remote-debugging-pipe`, so there is no\ndebug endpoint to attach to — but nothing is lost, because the session lives in\nthe profile on disk rather than in the process.\n\nThe match requires the resolved profile path to appear literally in a command\nline **and** the executable to look like a browser. Your everyday Chrome, other\nautomation browsers, and anything merely mentioning the path are never\ncandidates; when the filter is unsure it matches nothing.\n\n## Setup\n\nFrom PyPI (no clone needed):\n\n```bash\nuvx --from linkedin-sales-nav-mcp patchright install chromium # one-time browser download\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/nick-choudhary/linkedin-sales-nav-mcp\ncd linkedin-sales-nav-mcp\nuv sync\nuv run patchright install chromium # one-time browser download\ncp .env.example .env # optional; defaults are fine on your machine\n```\n\n### 1. Log in once\n\n```bash\nuvx linkedin-sales-nav-mcp --login # PyPI install\n# or, from a clone: uv run linkedin-sales-nav-mcp --login\n```\n\nA browser window opens. Sign into LinkedIn, open Sales Navigator, finish any\n2FA/checkpoint. The server detects the signed-in session and saves the\nprofile, then exits.\n\n### 2. Run the server\n\n```bash\nuvx linkedin-sales-nav-mcp # stdio, PyPI install\n# or, from a clone: uv run linkedin-sales-nav-mcp\n```\n\n### Claude Desktop / Claude Code config\n\nPyPI install:\n\n```json\n{\n \"mcpServers\": {\n \"sales-navigator\": {\n \"command\": \"uvx\",\n \"args\": [\"linkedin-sales-nav-mcp\"]\n }\n }\n}\n```\n\nFrom a clone:\n\n```json\n{\n \"mcpServers\": {\n \"sales-navigator\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"--project\", \"/path/to/linkedin-sales-nav-mcp\", \"linkedin-sales-nav-mcp\"]\n }\n }\n}\n```\n\nNo secrets in the config — the session lives in the browser profile.\n\n**Use `--project`, not `--directory`.** Both point uv at the repo, but\n`--directory` *changes the working directory* to it, which would send your\nexports into the repo instead of the project you are working in. `--project`\nleaves the working directory alone, which is what the export layout below\nexpects.\n\n### Installing it once, for every project\n\nPointing each config at a repo path gets tedious. Install the command onto your\nPATH instead:\n\n```bash\nuv tool install linkedin-sales-nav-mcp # from PyPI\n# or: uv tool install /path/to/linkedin-sales-nav-mcp (from a clone)\n```\n\nThen every project's config is just:\n\n```json\n{\n \"mcpServers\": {\n \"sales-navigator\": {\n \"command\": \"linkedin-sales-nav-mcp\"\n }\n }\n}\n```\n\nNo path, no flags, and nothing to update when you move the repo. Re-run the\ninstall with `--force` after pulling changes to pick them up.\n\nEither way the database is shared and the login carries over, so a new project\nneeds no `--login` of its own — only its own `.mcp.json` entry.\n\n### One server at a time\n\nConfigure it in as many projects as you like, but only run one at once. The\nbrowser profile is a persistent Chromium profile and Chromium takes an\nexclusive lock on it, so a second server starting while the first is live will\nfail to launch its browser. If you use `uv run`, the first server also holds\nthe repo's `.venv`, and a second `uv run` can fail while trying to sync it.\n\n### Environment variables\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `USER_DATA_DIR` | `~/.linkedin-sales-nav/profile` | Persistent browser profile |\n| `HEADLESS` | `false` | `false` = visible window (safest); `true` = headless (more detectable) |\n| `CHROME_PATH` | — | Use your own Chrome instead of bundled Chromium |\n| `PROXY_SERVER` | — | Leave empty on your own machine; only for a residential exit node if remote |\n| `IDLE_BROWSER_TIMEOUT` | `3600` | Close the browser after this many idle seconds; relaunches on demand. `0` keeps it open |\n| `NAV_TIMEOUT` / `CAPTURE_WAIT` / `LOGIN_TIMEOUT` | `60` / `25` / `300` | Timeouts (s) |\n| `TOOL_TIMEOUT` | `600.0` | Per-tool MCP timeout (s) — must exceed the pacing budget below |\n| `PACING_ENABLED` | `true` | Human-like delays between pages (see below) |\n| `PAGE_DELAY_MIN` / `PAGE_DELAY_MAX` | `3.0` / `8.0` | Random dwell before advancing a page (s) |\n| `LONG_PAUSE_EVERY` | `5` | Take a longer break every N pages (`0` disables) |\n| `LONG_PAUSE_MIN` / `LONG_PAUSE_MAX` | `20.0` / `45.0` | Length of that break (s) |\n| `STATE_DIR` | `~/.linkedin-sales-nav` | Where `sales_nav.db` and raw captures live — follows you between projects |\n| `OUTPUT_DIR` | `output` | Where JSON/CSV exports are written, relative to where the server runs |\n| `TRANSPORT` / `HOST` / `PORT` / `HTTP_PATH` | `stdio` / `127.0.0.1` / `9000` / `/mcp` | Transport |\n| `LOG_LEVEL` | `WARNING` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |\n\n## Where the data goes\n\nTwo directories, because the data has two lifetimes.\n\n**State** lives in `` (default `~/.linkedin-sales-nav`, beside the\nbrowser profile): the SQLite database at `sales_nav.db` plus any raw captures\nunder `/raw/`. It belongs to your LinkedIn account rather than to any\none project, so it is the same database wherever you launch the server from —\n`list_queries` shows one history across every folder.\n\n**Exports** are project artifacts, so they resolve against the working\ndirectory. `export_results` writes JSON/CSV into `//`\n(default `output//`), landing in whichever project you ran the search\nfor. The database stays the source of truth; exports are generated from it on\ndemand.\n\n> **Upgrading from 1.0.** The database used to live in `output/sales_nav.db`\n> relative to the launch directory. As of 1.1 it is at\n> `~/.linkedin-sales-nav/sales_nav.db` and is no longer read from the old path,\n> so an existing `output/sales_nav.db` will look empty. Either move it (take\n> `sales_nav.db`, `sales_nav.db-wal`, `sales_nav.db-shm` and the `/`\n> directories together — the `-wal` file holds recent writes), delete it and\n> re-run your searches, or set `STATE_DIR=./output` to keep the old layout.\n\nSchema version 2 (`PRAGMA user_version = 2`):\n\n| Table | Holds |\n|-------|-------|\n| `queries` | One row per search URL: `url_hash`, status, `last_page`, `total_available`, `records_count` |\n| `leads` | People (34 columns): name parts, `member_id`, title, company + `company_id`, industry, location, tenure, `open_link`, `premium`, `raw_json` |\n| `accounts` | Companies (16 columns): `company_id`, name, industry, headcount range, description, `raw_json` |\n| `positions` | 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 |\n| `badges` | Lead/account highlight badges (shared connections, \"recently changed jobs\", etc.) |\n\nTwo things worth knowing:\n\n- **`raw_json` is always stored.** LinkedIn's internal API is undocumented and\n shifts over time, so the complete original element is kept on every row. If\n the normalizer misses a field, it can be recovered later without re-scraping.\n- **Records de-duplicate across runs.** `UNIQUE(url_hash, record_key)` plus\n `INSERT OR IGNORE` means resuming, re-running, or overlapping searches never\n create duplicate rows.\n\nQuery it with anything that speaks SQLite:\n\n```bash\nsqlite3 ~/.linkedin-sales-nav/sales_nav.db \\\n \"SELECT full_name, title, company_name FROM leads LIMIT 10;\"\n```\n\nBoth the database and the exports contain real personal data. `output/` is in\n`.gitignore` for that reason — keep it that way. `` sits outside the\nrepo by default, so it is never a commit risk, but it is the copy worth\nprotecting: it accumulates across every project.\n\n## Pacing\n\nPages are not fetched back to back. After each page the server dwells for a\nrandom 3–8s before clicking \"Next\", and every ~5 pages (jittered ±1) it takes a\n20–45s break instead. Scroll rhythm is varied too — step count, distance, and\nthe gaps between them.\n\nThe reason is cadence, not speed: a page load every two seconds, forever, with\nno breaks, is a machine signature regardless of how genuine the session is. A\nfull 10-page call therefore takes a couple of minutes, most of it spent\ndeliberately idle. That is working as intended.\n\nTune with `PAGE_DELAY_*` / `LONG_PAUSE_*`, or set `PACING_ENABLED=false` to\ndisable the delays entirely (not recommended). Raise `TOOL_TIMEOUT` alongside\nany large increase.\n\n**This lowers your footprint; it does not make you invisible.** Volume is what\ngets accounts flagged, and no jitter setting changes how many profiles you\npulled today. Fetch what you need, spread it out, and use an account you own.\n\n## Example agent usage\n\n> **User:** Find heads of engineering at mid-size fintech companies in Berlin.\n>\n> **Agent:** builds/obtains a Sales Navigator search URL (paste one, or use a\n> URL-builder skill), then:\n>\n> ```\n> search_contacts(\n> search_url=\"https://www.linkedin.com/sales/search/people?query=(...)\",\n> pages=2\n> )\n> ```\n>\n> → `{\"url_hash\": \"a6ca...\", \"new_records_this_call\": 50, \"total_records\": 50,\n> \"next_page\": 3, \"status\": \"paused\", ...}` — the 50 records are now in\n> SQLite, not in the reply.\n>\n> **Agent:** then pulls what it needs for the answer:\n>\n> ```\n> get_results(url_or_hash=\"a6ca...\", limit=25) # a sample to reason over\n> export_results(url_or_hash=\"a6ca...\", format=\"csv\") # or a file on disk\n> ```\n\n## Important honesty notes\n\n- **Field mapping is best-effort.** We capture LinkedIn's internal sales-api\n JSON, which is undocumented and changes over time. The normalizer\n (`sales_nav_mcp/normalize.py`) pulls the fields that have been stable. If one\n looks empty, you have two ways back to ground truth without re-scraping: the\n `raw_json` column on every row, or `include_raw=true` on a search, which\n writes the complete untouched API responses to `//raw/`.\n Extend the mapper from those. This is the intended maintenance path.\n- **Pagination selectors** for the \"Next\" control can change; the code tries\n several fallbacks and stops cleanly if none match. If deep pagination stops\n early, update `_NEXT_SELECTORS` in `sales_nav_mcp/capture.py`.\n- **Run it on your own machine.** A datacenter/cloud IP re-introduces the\n logout risk this design exists to avoid.\n- Scraping LinkedIn is subject to LinkedIn's Terms of Service. Use an account\n you own, at conservative rates.\n\n## Development\n\n```bash\nuv run pytest # full unit suite, no browser and no network\n```\n\nCovered: URL validation, JSON normalization against real captured element\nshapes (with synthetic values), the SQLite store and exports, and pacing —\nboth the delay arithmetic and its wiring into the capture loop, using a fake\npage and an injected clock so the suite never actually waits.\n\nNot covered: the live browser path. Exercise that by running `--login`\nfollowed by a real search.\n\nEvery push and PR runs the same suite plus ruff lint/format checks in CI\n(Linux on Python 3.12–3.14, Windows and macOS on 3.13), and the release\npipeline re-runs the tests before anything is published.\n\n## License and who can use this\n\n**MIT** — see [LICENSE](LICENSE). In plain terms: anyone can use, copy,\nmodify, and redistribute this software, commercially or otherwise, free of\ncharge. The only requirement is keeping the copyright and license notice in\ncopies; the software comes with no warranty.\n\nWhat the license does **not** cover is your relationship with LinkedIn:\n\n- This project is **not affiliated with, endorsed by, or supported by\n LinkedIn**. It automates a browser against LinkedIn's own web application.\n- Automated access to LinkedIn is restricted by LinkedIn's Terms of Service.\n Using this server is **your decision and your responsibility** — use an\n account you own, keep volumes conservative, and accept that the account\n could be restricted.\n- The data you collect is real personal data about real people. Handling it\n may fall under privacy laws such as the GDPR or CCPA depending on where you\n and the data subjects are. Compliance is on you, not on this tool.\n",
"bytes": 30036,
"sha": "90061b3b4bdf851a633c51b51a1a0827d26fe2313e1d2244f0f399114125d9bb",
"repo_slug": "nick-choudhary/linkedin-sales-nav-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_nick_choudhary_linkedin_sales__89babeba/readme"
}
![\"An](\"docs/banner.jpg\")
\n