linkedin-mcp

A Model Context Protocol server that drives your own logged-in LinkedIn session in a real Chromium browser, with an explicit confirmation step in front of every write.

⚠️ Read this first

This is not a normal API client. Please read all of this before you install it.

• It drives a real, logged-in browser session as you. The server launches Chromium, restores your saved LinkedIn cookies, and clicks the same buttons a human would.

• It does not use the official LinkedIn API. There is no OAuth app, no partner agreement, and no supported integration behind it. It is browser automation of the public website.

• Automating LinkedIn this way operates outside LinkedIn's User Agreement. LinkedIn's terms prohibit scraping and automated access to the site.

• Your account can be rate-limited, restricted, or permanently banned. That risk is real and it is not hypothetical. LinkedIn detects automation, and enforcement can arrive without warning and without appeal.

• Your session cookies live on this machine. A successful login writes a Playwright storageState file to local disk. Anyone who can read that file can act as you on LinkedIn.

• Use is entirely at the account owner's own risk. There is no warranty here, expressed or implied, and no mitigation for a suspended account.

Three design decisions follow from the above and are not configurable:

1. Single account, single user. The server has one state directory holding one saved session. There is no multi-account support and no notion of "users" — it is a local tool for the person sitting at the keyboard.

2. Every write action requires explicit confirmation. Posting, connecting, messaging, and applying are all two-call handshakes. A single tool call can never send anything to LinkedIn. See the next section.

3. The server will never solve a CAPTCHA. It will not type your password, will not clear a 2FA prompt, and will not attempt to defeat a security checkpoint. When LinkedIn puts up a challenge, the server stops and tells you to handle it yourself in a normal browser.

If any of that is unacceptable for your account, do not install this.

Related MCP server: LinkedIn MCP Server

How confirm-before-execute works

Every write tool (linkedin_create_post, linkedin_send_connection_request, linkedin_send_message, linkedin_apply_to_job) is a two-call handshake:

Call 1 — preview. Call the tool with its real arguments and no confirm. The server inspects the page, works out exactly what would happen, and returns a preview envelope. Nothing is submitted, and your daily quota is not consumed.

{
  "profileUrl": "https://www.linkedin.com/in/dana-whitfield-example/",
  "note": "Hi Dana — we both worked on the OpenTelemetry collector. Would like to connect."
}

Call 2 — confirm. Re-issue the same call with confirm: true. Optionally echo the previewToken you were handed; if you do, the server verifies that the arguments have not changed since the preview and fails with confirmation_mismatch if they have.

{
  "profileUrl": "https://www.linkedin.com/in/dana-whitfield-example/",
  "note": "Hi Dana — we both worked on the OpenTelemetry collector. Would like to connect.",
  "previewToken": "9f2c41ab77e05d13",
  "confirm": true
}

The preview envelope looks like this (a real linkedin_send_connection_request preview):

{
  "status": "preview",
  "action": "linkedin_send_connection_request",
  "executed": false,
  "confirmationRequired": true,
  "summary": {
    "profileUrl": "https://www.linkedin.com/in/dana-whitfield-example/",
    "name": "Dana Whitfield",
    "headline": "Staff Engineer, Observability",
    "note": "Hi Dana — we both worked on the OpenTelemetry collector. Would like to connect.",
    "noteLength": 88,
    "notePreview": "Hi Dana — we both worked on the OpenTelemetry collector. Would like to connect.",
    "connectionDegree": 2,
    "connectionDegreeLabel": "2nd",
    "connectPathway": "direct",
    "alreadyPending": false,
    "wouldSucceed": true
  },
  "previewToken": "9f2c41ab77e05d13",
  "quota": {
    "action": "connectionRequests",
    "used": 3,
    "cap": 20,
    "remaining": 17,
    "resetsAt": "2026-08-25T07:00:00.000Z",
    "allowed": true
  },
  "warnings": [],
  "howToConfirm": "Nothing has been sent to LinkedIn yet. To execute, re-issue the exact same `linkedin_send_connection_request` call with `confirm: true` (optionally echoing `previewToken: \"9f2c41ab77e05d13\"` so the arguments are verified as unchanged)."
}

Notes on reading a preview:

• executed: false and confirmationRequired: true are always present on a preview. An executed result instead carries "status": "executed", "executed": true, and a result object.

• warnings is where the server tells you about anything it is unhappy about — a truncated post, an over-long connection note, an exhausted quota, dry-run mode.

• If the preview says the call cannot succeed (already connected, invitation already pending, no Connect control, not a 1st-degree connection), howToConfirm says so plainly and confirming will be refused with invalid_input without spending quota.

• previewToken is a short digest over the action name and a canonicalized copy of the payload. It is a mismatch guard, not a security token.

Requirements

• Node.js 20 or newer ("engines": { "node": ">=20" }).

• A desktop environment that can open a visible browser window — interactive login requires one.

• Playwright's Chromium build (installed below).

Setup

Install dependencies:

npm install

Download the Chromium build Playwright drives:

npx playwright install chromium

Create your environment file (every variable in it is optional, and it holds no credentials):

cp .env.example .env

Create your config file (daily caps and timeouts only):

cp config.example.json config.json

Compile TypeScript to dist/:

npm run build

First run, in order

Nothing here touches your LinkedIn account until the very last step.

1. npm install

2. npx playwright install chromium

3. cp .env.example .env and cp config.example.json config.json — both optional, neither holds credentials

4. npm run build

5. npm test — 324 hermetic unit cases; no browser, no network

6. npm run verify:dry — drives all 11 tools against local fixtures, so you find out the wiring works before pointing it at your account (details)

7. Register the server with your MCP client, with --dry-run in args first (details). Confirm your client lists 11 tools and that a write tool returns a preview.

8. Drop --dry-run from args, restart your client, and call linkedin_login (details). This is the first step that reaches linkedin.com. A visible Chromium window opens and you sign in by hand.

9. Call linkedin_session_status to confirm the saved session works.

10. Optional, once you have a session: npm run verify:live then npm run verify:read-tools — the two read-only checks that tell you whether the selectors still match today's LinkedIn (details). Both refuse to write anything.

Step 8 is the boundary. Everything before it is reversible by deleting a directory.

Logging in

There is no credential configuration anywhere in this project — by design. You sign in by hand, once, in a real browser window.

1. Call the linkedin_login tool. It takes no arguments.

2. A real, visible Chromium window opens on LinkedIn's login page. It is visible even if you configured headless: true; interactive login always forces a headed browser.

3. You type your email and password, and you clear whatever LinkedIn asks for next — an SMS or authenticator code, an email PIN, a device confirmation, a CAPTCHA. The server does not type credentials, does not read the password field, and does not touch challenge widgets. It just polls every two seconds, waiting to see a signed-in identity element in LinkedIn's navigation.

4. Take your time. The wait is bounded by loginTimeoutMs, which defaults to 300000 (five minutes). Raise it in config.json if you need longer.

5. Once LinkedIn shows a signed-in feed, the browser session is written to storageState.json inside the state directory, with file permissions 0600 (owner read/write only). That file is gitignored.

6. Every later tool call reuses that saved session. You should not need to log in again for weeks.

Check on the session at any time with linkedin_session_status (no arguments). It loads the feed once and reports:

{
  "valid": true,
  "lastVerified": "2026-08-24T18:42:10.114Z",
  "sessionSavedAt": "2026-08-11T09:03:55.002Z"
}

When it reports valid: false it includes a reason (for example, that LinkedIn redirected the feed to its sign-in page). No cookie or session content is ever returned by this tool, or by any other.

Sessions expire. When they do, tools start failing with session_expired and the fix is always the same: run linkedin_login again and sign in by hand.

Rate limits & pacing

The server enforces its own daily caps and inserts a randomized delay before browser actions. This is the single most important protection your account has, and the defaults are conservative on purpose.

config.example.json — copy it to config.json and edit:

{
  "dailyCaps": {
    "connectionRequests": 20,
    "messages": 30,
    "posts": 5,
    "jobApplications": 10
  },
  "delayRangeMs": {
    "min": 1500,
    "max": 6000
  },
  "headless": false,
  "navigationTimeoutMs": 30000,
  "actionTimeoutMs": 15000,
  "loginTimeoutMs": 300000
}

The four daily caps

How they behave:

• A cap is only consumed on a confirmed execution. Previews report your current quota but never spend it, and a call the server refuses outright does not spend it either.

• Counts are persisted to counters.json in the state directory, so a server restart does not reset them.

• When a cap is reached, the tool fails with rate_limited instead of acting. Setting a cap to 0 disables that action entirely.

• Every preview and executed envelope carries a quota block with used, cap, remaining, resetsAt, and allowed.

Randomized delay

delayRangeMs is the range the server sleeps for, uniformly at random, before browser actions — by default 1500 ms to 6000 ms. Randomization matters: a fixed interval is a machine signature. min may equal max (a fixed delay) and min must not exceed max, or config loading fails with config_invalid.

Caps reset at local midnight

Counters are keyed on the local calendar date, so all four caps reset at midnight in your own timezone — not at UTC midnight, and not on a rolling 24-hour window. resetsAt in the quota block is that next local midnight, serialized as a UTC ISO timestamp.

Start lower than the defaults

The shipped defaults are a ceiling, not a recommendation. If your account is new, has few connections, or has never been automated before, start well below them — say connectionRequests: 5, messages: 5, posts: 1, jobApplications: 2 — and raise them slowly over weeks while watching for LinkedIn warnings. A burst of activity that looks nothing like your normal usage is exactly what gets accounts restricted.

Tool reference

Eleven tools, in the order the server registers them.

The four scrape/jobs tools below (linkedin_scrape_profile, linkedin_scrape_feed, linkedin_search_jobs, linkedin_apply_to_job) are documented from the shared contract in src/types.ts and src/selectors.ts. If your client's tools/list output disagrees with an argument name here, tools/list is authoritative — the server always reports its real schema.

linkedin_login

Opens a visible Chromium window and waits for you to sign in yourself, including any 2FA or CAPTCHA step. Saves the session to local disk on success. Takes no arguments. Not available under --dry-run.

{}

linkedin_session_status

Reports whether the saved session still works, when it was saved, and when it was last verified. Loads the feed once to check. Read-only. Always reports valid under --dry-run. Takes no arguments.

{}

linkedin_create_post (write — confirmation required)

Publishes a text post to your own feed. Consumes the posts cap.

Preview:

{
  "text": "Spent the week reading Playwright's tracing internals. Notes soon.",
  "visibility": "connections"
}

Confirm:

{
  "text": "Spent the week reading Playwright's tracing internals. Notes soon.",
  "visibility": "connections",
  "confirm": true
}

• text — required, 1 to 3000 characters. Over ~1300 characters LinkedIn collapses the post behind "see more"; the preview warns you.

• visibility — optional, "public" or "connections". Defaults to "public".

• mediaUrl — optional URL. The server never fetches remote media. Passing it warns at preview and is hard-refused with invalid_input on confirm.

• previewToken — optional; echo it to have your arguments verified as unchanged.

• confirm — optional boolean; must be exactly true to execute.

linkedin_send_connection_request (write — confirmation required)

Sends a connection invitation, optionally with a note. Consumes the connectionRequests cap.

Preview:

{
  "profileUrl": "https://www.linkedin.com/in/dana-whitfield-example/",
  "note": "Hi Dana — we both worked on the OpenTelemetry collector. Would like to connect."
}

Confirm:

{
  "profileUrl": "https://www.linkedin.com/in/dana-whitfield-example/",
  "note": "Hi Dana — we both worked on the OpenTelemetry collector. Would like to connect.",
  "previewToken": "9f2c41ab77e05d13",
  "confirm": true
}

• profileUrl — required, non-empty. A full profile URL or a bare vanity slug.

• note — optional, at most 300 characters. Notes over 200 characters need LinkedIn Premium on many accounts, so the preview warns above 200.

• previewToken, confirm — as above.

Refused with invalid_input before touching your quota if the person is already a 1st-degree connection, an invitation is already pending, or the page exposes no Connect control.

linkedin_send_message (write — confirmation required)

Sends a direct message. Consumes the messages cap.

Preview:

{
  "profileUrlOrConversationId": "https://www.linkedin.com/in/dana-whitfield-example/",
  "text": "Thanks for the pointer to the collector RFC — that answered my question."
}

Confirm:

{
  "profileUrlOrConversationId": "https://www.linkedin.com/in/dana-whitfield-example/",
  "text": "Thanks for the pointer to the collector RFC — that answered my question.",
  "confirm": true
}

• profileUrlOrConversationId — required, non-empty. Either a profile URL/slug, or an existing conversation thread id (as in /messaging/thread/<id>/).

• text — required, 1 to 8000 characters.

• previewToken, confirm — as above.

In profile mode the recipient must be a 1st-degree connection; anyone else is refused with not_connected before quota is spent. This tool never sends InMail, and it never presses Enter in the composer — it clicks Send.

linkedin_scrape_profile

Reads one profile and returns a structured Profile: name, headline, about, location, connection degree, whether it is your own profile, experience entries, education entries, and skills. Read-only.

{
  "profileUrl": "https://www.linkedin.com/in/dana-whitfield-example/"
}

linkedin_scrape_feed

Reads recent posts from your feed and returns FeedPost entries: author name and headline, text, post URL, like and comment counts, and posted-at. Read-only.

{
  "count": 20
}

linkedin_search_jobs

Runs a LinkedIn job search and returns JobListing entries: jobId, title, company, location, whether it is Easy Apply, and the job URL. Read-only.

{
  "keywords": "site reliability engineer",
  "location": "Berlin, Germany",
  "easyApplyOnly": true,
  "count": 25
}

keywords is required. Everything else is optional:

• location — free-text place name, mapped onto LinkedIn's own location parameter.

• easyApplyOnly — restricts results to Easy Apply postings (LinkedIn's f_AL facet). Worth setting whenever you intend to apply through this server, since linkedin_apply_to_job handles Easy Apply only.

• datePosted — "past24h", "pastWeek" or "pastMonth".

• experienceLevel — "internship", "entry", "associate", "midSenior", "director" or "executive".

• remote — true restricts results to remote roles.

• count — how many postings to return (default 25, max 100). Results are lazy-loaded, so a large count means repeated scrolling with a randomized pause between each, and can take a while.

Those four facets may be passed either at the top level, as above, or grouped inside a filters object — both are accepted, and filters wins if you pass the same key twice:

{
  "keywords": "site reliability engineer",
  "filters": { "easyApplyOnly": true, "datePosted": "pastWeek", "remote": true },
  "count": 50
}

Cards that LinkedIn renders without a usable job id (promoted slots, placeholders) are skipped rather than returned half-populated, and counted in the skipped field of the response. The response also echoes the searchUrl it used, so you can open the identical query in your own browser.

linkedin_apply_to_job (write — confirmation required)

Submits a LinkedIn Easy Apply application. Consumes the jobApplications cap.

Preview:

{
  "jobId": "3912847561",
  "resumePath": "/Users/parthbansal/Documents/resume.pdf"
}

Confirm:

{
  "jobId": "3912847561",
  "resumePath": "/Users/parthbansal/Documents/resume.pdf",
  "confirm": true
}

• jobId — required. A bare job id, a /jobs/view/<id>/ URL, a search URL carrying ?currentJobId=, or a job urn all resolve to the same id.

• resumePath — optional absolute path to a resume file on this machine. A missing file fails with file_not_found. The file's contents are never logged.

• Postings that hand off to an external applicant-tracking system fail with external_application; postings without an Easy Apply control fail with not_easy_apply. Read the preview before confirming — it is your only chance to see which questions the form is about to answer on your behalf.

• previewToken, confirm — as above.

linkedin_list_pending_invites

Lists pending invitations as PendingInvite entries: name, headline, profile URL, sent-at, and direction. Read-only.

{
  "direction": "received",
  "count": 25
}

• direction — optional, "received" (someone invited you) or "sent" (you invited them). Defaults to "received".

• count — optional integer, 1 to 100. Defaults to 25.

linkedin_list_connections

Lists your connections as ConnectionSummary entries: name, headline, profile URL, and connected-at. Read-only.

{
  "count": 50,
  "query": "observability"
}

• count — optional integer, 1 to 200. Defaults to 50.

• query — optional. A local, case-insensitive substring filter applied to the connections the server already read; it is not sent to LinkedIn as a search.

MCP client configuration

The server speaks JSON-RPC over stdio and is meant to be launched by your MCP client, not by hand. Build first (npm run build), then point your client at dist/server.js.

Because the server resolves config.json, the state directory, and fixtures/ relative to its working directory — and your MCP client's working directory is usually not this project — it is worth setting the absolute paths explicitly in the env block.

Claude Code / Claude Desktop

In claude_desktop_config.json:

{
  "mcpServers": {
    "linkedin": {
      "command": "node",
      "args": ["/Users/parthbansal/Desktop/claude code/linkedin-mcp/dist/server.js"],
      "env": {
        "LINKEDIN_MCP_CONFIG": "/Users/parthbansal/Desktop/claude code/linkedin-mcp/config.json",
        "LINKEDIN_MCP_STATE_DIR": "/Users/parthbansal/Desktop/claude code/linkedin-mcp/.linkedin-mcp",
        "LINKEDIN_MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Cursor

In .cursor/mcp.json:

{
  "mcpServers": {
    "linkedin": {
      "command": "node",
      "args": ["/Users/parthbansal/Desktop/claude code/linkedin-mcp/dist/server.js"],
      "env": {
        "LINKEDIN_MCP_CONFIG": "/Users/parthbansal/Desktop/claude code/linkedin-mcp/config.json",
        "LINKEDIN_MCP_STATE_DIR": "/Users/parthbansal/Desktop/claude code/linkedin-mcp/.linkedin-mcp",
        "LINKEDIN_MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Generic stdio client (for example Codex CLI)

Any client that launches an stdio MCP server needs the same three things — a command, its arguments, and an environment:

{
  "name": "linkedin",
  "command": "node",
  "args": ["/Users/parthbansal/Desktop/claude code/linkedin-mcp/dist/server.js"],
  "env": {
    "LINKEDIN_MCP_CONFIG": "/Users/parthbansal/Desktop/claude code/linkedin-mcp/config.json",
    "LINKEDIN_MCP_STATE_DIR": "/Users/parthbansal/Desktop/claude code/linkedin-mcp/.linkedin-mcp",
    "LINKEDIN_MCP_LOG_LEVEL": "info"
  }
}

Codex CLI uses TOML rather than JSON, but the mapping is one-to-one: command = "node", args = ["/Users/parthbansal/Desktop/claude code/linkedin-mcp/dist/server.js"], plus an [env] table.

Safe experimentation

Add "--dry-run" to args to register a fully-functional server that cannot touch your account:

"args": [
  "/Users/parthbansal/Desktop/claude code/linkedin-mcp/dist/server.js",
  "--dry-run"
]

In dry-run mode no request reaches linkedin.com and no post, invitation, message, or application is ever submitted. This is the right way to let an agent explore the tool surface for the first time.

Other flags the server accepts: --read-only, --headless, --config <path>, --log-level <debug|info|warn|error>, and -h / --help (which prints to stderr, because stdout carries the protocol). Unknown flags are a hard error — a mistyped --dry-runn must never leave you believing you are in dry-run mode when you are not. Precedence throughout is command-line flags > environment > config.json > defaults.

Every environment variable is documented in .env.example; all of them are optional, and none of them hold credentials.

Read-only mode

--read-only is the other safety switch, and it is not the same promise as --dry-run:

Use it when you want an agent to read your actual LinkedIn — your real feed, your real connections, live job listings — with no possibility of a write. The four write tools (linkedin_create_post, linkedin_send_connection_request, linkedin_send_message, linkedin_apply_to_job) come back as read_only_mode errors; the other seven work normally.

Three details worth knowing:

• The refusal happens before the tool runs, in the one wrapper every tool is registered through (src/server.ts), so there is no argument shape that slips past it and no per-tool check anyone can forget to add. All eleven tools stay listed — a client discovers the full surface and learns which ones are unavailable by calling them, rather than seeing a mysteriously short tool list.

• Previews are refused too, not just confirm: true. That is deliberate and it is the non-obvious part: linkedin_apply_to_job builds its preview by opening the job and clicking Easy Apply to read the form, which LinkedIn can record as a started application. A bar that allowed "just the preview" would not have been read-only.

• linkedin_login stays available. It writes storageState.json, so it is not readOnlyHint, but it changes nothing on LinkedIn — and refusing it would make read-only mode impossible to authenticate in the first place.

Set it however suits your client: --read-only on the command line, LINKEDIN_MCP_READ_ONLY=1 in the environment, or "readOnly": true in config.json. It defaults to off, so adding this feature cannot silently change an existing install. A malformed value (LINKEDIN_MCP_READ_ONLY=enabled) is a config_invalid error rather than a guess — guessing would be dangerous in either direction. Startup says so on stderr, twice, so the mode is never in doubt:

{"level":"warn","msg":"READ-ONLY: reads go to the real linkedin.com, but linkedin_create_post, linkedin_send_connection_request, linkedin_send_message and linkedin_apply_to_job will be refused with `read_only_mode`","readOnly":true,"refused":4}
{"level":"info","msg":"linkedin-mcp ready on stdio","version":"0.1.0","tools":11,"dryRun":false,"readOnly":true,"headless":false}

This mode is also what npm run verify:read-tools runs under — it will not start unless that second line reports readOnly: true and dryRun: false.

Development

Type-check without emitting:

npm run typecheck

Run the unit tests:

npm test

Recompile on save:

npm run dev

--dry-run

npm run dry-run starts the built server with --dry-run. In that mode the browser is pointed at local HTML fixtures in fixtures/ instead of linkedin.com, and the final submit click of every write flow is skipped, so a confirmed action walks the entire code path — validation, quota check, dialog interaction — and then stops short of doing anything. Executed results carry dryRun: true, and previews warn you that dry-run is on. linkedin_login is unavailable, and linkedin_session_status always reports valid.

The fixtures cover the profile page (in three variants — a 2nd-degree profile with a direct Connect button, a 2nd-degree profile whose Connect sits behind the "More" menu, and a 1st-degree connection with a working message composer), the feed, job search, a job detail page for both Easy Apply and an external applicant-tracking system, messaging, invitations, and connections. Develop here. There is no reason for day-to-day work on this server to touch your real account.

Which fixture a URL resolves to is decided by an ordered list of substring rules in src/fixtures.ts. The order is load-bearing — /mynetwork/invite-connect/connections/ contains /mynetwork/invit, and /in/tomas-eriksen contains /in/ — so specific rules sit above general ones and tests/fixtures.test.ts locks that ordering in place.

Verifying without LinkedIn

npm run verify:dry

This boots the compiled server in --dry-run, speaks JSON-RPC to it over stdio as a real MCP client would, and exercises all 11 tools across 23 cases — every read tool against its fixture, every write tool through a full preview → confirm handshake, and the refusals that matter (a stale previewToken, an over-long post, a message to a 2nd-degree profile, an external job posting, linkedin_login under dry-run). It asserts the envelope contracts too: a preview must report executed: false, a confirm must report executed: true, and stdout must carry nothing but JSON-RPC.

It refuses to run at all unless the server's own startup line confirms dryRun: true, so it cannot accidentally act on your account. It needs a working Chromium — everything but session_status opens a browser page — and it exits non-zero on any failure, sorting them into selector/logic failures (the server is wrong) and harness failures (the sweep is wrong).

Validating selectors against real LinkedIn

npm test proves the pure logic. npm run verify:dry proves the tools drive a page correctly — but against fixtures this project wrote. Neither can tell you whether a selector still matches today's LinkedIn. Only a live run can, and a live run against your own account is exactly where an accidental click is unacceptable. So:

npm run build && npm run verify:live

This opens allow-listed LinkedIn pages with your saved session, asks every selector chain "do you match anything visible?", and prints what it saw. It fills no field, submits no form, and clicks no button that starts a write.

Each page gets a detailed section — what was requested, what URL actually came back, what kind of page it was judged to be, and one block per selector:

── Home feed ──
   requested  https://www.linkedin.com/feed/
   observed   https://www.linkedin.com/feed/
   page kind  feed

  ✓ post.startPostButton — found
      matched: button.share-box-feed-entry__trigger
  ✓ feed.post — found (fallback #2 of 4)
      matched: div.feed-shared-update-v2
  ✗ feed.likeCount — not found
      verdict:  likely-empty-state (content layer)
      tried:    3 candidate(s)
        - span.social-details-social-counts__reactions-count  no match
      why:      …
      next:     …

  skipped on this page (9):
    – post.editor — inside a dialog that can only be opened by starting a write action

…followed by the flat one-line-per-selector rollup, aggregated across every page (found anywhere counts as found):

SELECTOR VALIDATION
✓ profile.name — found
✓ profile.headline — found
⚠ connections.connectionCard — matched an empty container (not validated)
✗ jobs.easyApplyButton — not found
~ feed.likeCount — unprovable under GET-only — prove it with `npm run verify:read-tools`
✓ messaging.messageBox — found

✓ records which candidate matched and flags when it was a fallback rather than the primary hook.

⚠ is the one verdict worth explaining, because it is the failure mode this report exists to prevent. LinkedIn's newer pages paint a card's outer shell before (or without) its contents, so a container selector can match 36 elements on a page that holds none of the data those cards are supposed to hold. Every child selector probed inside such a shell then misses — and a naive reading blames those children. So a container that matched an element but contained none of the children the manifest expects inside it is reported as not validated, its children's misses are re-classified as "nothing can be concluded", and a required empty container fails the run exactly like a miss.

✗ is not automatically a selector bug — every miss is classified (missing auth / wrong page state / empty container / blocked request / POST-rendered / legitimate empty state / DOM change), the candidates tried are listed with their match counts, and any equivalent element found on the page is dumped with its tag, role, aria-label, id, data-* and text so you can judge for yourself. The closing fixes block is split by how strong the evidence is: OBSERVED means an equivalent element was actually seen on the page and its attributes are printed for you; SUSPECTED means only that a selector produced nothing and no cheaper explanation applied — a "go and look in your own browser" prompt, never an instruction to rewrite a selector. The script never edits selectors.ts for you.

~ is the honest admission in this report. LinkedIn serves some pages — the feed, profiles, invitations, connections — from an RSC payload that arrives over a POST, and safety layer 2 aborts every POST before it leaves the machine. Those selectors therefore cannot match here, no matter how correct they are. Rather than print them beside real misses, where they read as 36 simultaneous DOM changes, they are pulled into their own UNPROVABLE UNDER GET-ONLY block, excluded from the missed count, and pointed at the one thing that can prove them: npm run verify:read-tools (below). The fix is never to widen the request filter.

– means the element only exists inside a dialog that opens by starting a write, or only after one completes; unreachable read-only, so it is reported in a closing NOT VALIDATED block rather than hidden.

Exit codes: 0 = every required selector this run could test was found, 1 = a required selector missed or matched only an empty container, 2 = the run never happened (no build, no session, a challenge, a launch failure). Non-required misses are reported but do not fail the run, because most are legitimate empty states. A ~ key cannot fail the run either — the run had no way to test it, and letting profile.name fail every single time would make exit 1 mean nothing. That is what makes the pairing below load-bearing rather than optional: verify:read-tools is where those keys can actually fail.

Flags:

The safety posture is five independent layers, each sufficient on its own:

1. No write tool is imported. The script does not load dist/registry.js and cannot invoke a write tool even by accident. It also never uses a tool's preview half — see the read-only note above for why linkedin_apply_to_job's preview is not safe.

2. Route-level kill switch. Every request is inspected; anything not GET/HEAD/OPTIONS is aborted before it leaves the machine, as is any URL carrying a state-changing marker — logout above all, because LinkedIn's sign-out is reachable by a plain GET and a naive "GET is safe" rule would destroy the very session you asked to verify.

3. Navigation allowlist. Every goto target must pass isAllowedValidationUrl. An unrecognized LinkedIn path is refused rather than assumed harmless.

4. No clicking. The only click available is opening the profile overflow menu, under the explicit --probe-menus opt-in. Connect / Send / Submit / Apply are never even located as click targets.

5. Challenge hard stop. A CAPTCHA, checkpoint or auth wall ends the run with instructions to clear it in your own browser. Nothing is solved, bypassed, or retried.

It needs a session it did not create: if storageState.json is missing or LinkedIn no longer accepts it, the script stops and tells you to run linkedin_login yourself. It never types a credential. It also refuses to run when dry-run is configured — validating fixtures against fixtures would prove nothing.

One privacy note: both --screenshots and --json write files containing real content from your account — page images, profile text, aria-labels. Nothing uploads them. Screenshots land in the gitignored state directory (.linkedin-mcp/screenshots/), but the --json path is wherever you point it, so choose it deliberately or keep it inside the state directory.

The pure logic underneath it (the selector manifest, the page classifier, the URL allowlist, the miss classifier) is exported from src/validation.ts and covered by tests/validation.test.ts, so the safety rules are provable without a browser.

Proving the selectors verify:live structurally cannot

npm run build && npm run verify:read-tools

Safety layer 2 above is a hard kill switch: every non-GET request is aborted. That is the layer worth keeping — but it has a consequence. LinkedIn's feed, profile, invitations and connections pages fetch their actual content over POST /flagship-web/rsc-action/…, so under verify:live those pages render a shell and 36 selectors miss for a reason that has nothing to do with whether they are correct. No amount of re-running fixes that, and the obvious "fix" — allowing those POSTs — would trade a real safety guarantee for a diagnostic convenience.

This harness proves them the other way round, at no new safety cost. It boots the compiled server with --read-only and calls the five read tools you already use over stdio:

The reasoning is simple: if linkedin_scrape_profile comes back with a name, a headline and three job titles, then the selectors that read them matched real DOM on the real site. A field that comes back empty on a page that did return records is the actual signal — that is a selector to look at.

Why this is not a new hole in the safety posture:

• These five tools never click a write control. Not in preview, not in confirm — there is no write path in them to reach. They are the same code paths you invoke from your MCP client every day.

• No new exception to the kill switch. The harness does not touch it. It runs the server normally, which is where those POSTs were always allowed.

• Read tools consume no daily quota. The caps in RateLimiter cover connectionRequests, messages, posts and jobApplications only, so a validation run cannot eat into your posting or connecting budget.

• Five gates run before any page work, in this order: the call plan is checked for a mutating tool, a confirm/previewToken argument, an out-of-range count and a non-https profile URL; the server's own startup line must report readOnly: true and dryRun: false; every planned tool must exist in tools/list and advertise annotations.readOnlyHint: true; and linkedin_session_status must come back valid. A verification_required anywhere is a hard stop — no challenge is ever solved, bypassed or retried.

It needs a real signed-in session (run linkedin_login first) and it will not run under dry-run — fixture data would prove nothing about live selectors. Output is per-field, with the manifest keys each field carries:

profile (your own)   linkedin_scrape_profile
  records 1 · page profile
    proven       name                        1/1 → profile.name
    proven       experience[]                1/1 → profile.experienceItem
    proven       experience[].title          3/3 → profile.itemTitle
    empty        experience[].description    0/3 → profile.itemDescription
      note: many roles genuinely have no description
    no-records   skills[]                    0/0 → profile.skillItem

proven = at least one populated value, so the selector matched. empty = records came back and not one carried this field — this is the finding, and the manifest's own note on that field is printed beside it so you can weigh "the selector broke" against "nobody filled this in". no-records = the collection was empty, so nothing was observable (a genuinely empty invitations list reads this way, which is why it is not counted as a failure). not-observed = the tool did not run, so nothing was measured. Anything no read tool reads at all — feed.seeMoreButton and the four profile section containers, five keys in total — is listed separately as hand-check-only rather than left as a silent gap in the coverage claim.

Flags — note these take =, unlike verify:live's space-separated form, and an unrecognized argument exits 2 rather than being ignored: --plan (print the six planned calls and exit, opening nothing), --headed, --profile=<url>, --keywords=<text>/--location=<text>, --feed-count=<n>/--jobs-count=<n>/--invites-count=<n>/--connections-count=<n> (each capped at 50), --direction=received|sent|both, --only=<tool>, --state-dir=<path>, --timeout=<ms>, --json[=<path>], --verbose/-v.

The --json report lands in .linkedin-mcp/ by default and contains real content from your account, so the same privacy note as --json above applies — and the harness refuses to write to validation-report.json, so a run cannot clobber the live validator's report.

Exit codes: 0 = nothing came back measurably empty. 1 = at least one field was empty on a page that did return records — go look at that selector. 2 = the run never happened (no build, a gate refused the plan, no session, a challenge, Chromium could not launch).

Tests

The suite is run by Vitest (tests/**/*.test.ts) and currently covers the rate limiter (src/rateLimiter.ts), the config loader (src/config.ts), fixture routing (src/fixtures.ts), the live-validation logic (src/validation.ts), and read-only mode — 324 cases in five files. All of them are hermetic by construction: every case runs against a fresh mkdtemp directory, the environment is passed in explicitly rather than read from process.env, and the rate limiter's clock, sleep, and randomness are injected through RateLimiterDeps. They make no network calls and launch no browser.

Anything that needs a browser lives in the dry-run sweep above, not in the unit suite — which is why npm test finishes in under a second and needs nothing installed beyond node_modules.

Conventions worth knowing before you edit

• Nothing may write to stdout. stdout is the JSON-RPC channel; one stray byte desynchronizes framing and the client drops the connection. All diagnostics go to stderr through the Logger.

• The project is ESM with moduleResolution: "NodeNext", so relative imports must end in .js even in TypeScript source.

• src/types.ts and src/errors.ts are the shared contract. src/selectors.ts is strings and pure functions only.

Troubleshooting

"I started it and nothing happens" — that is success

Run npm start by hand and you will see one line on stderr and then apparent silence:

{"ts":"...","level":"info","msg":"linkedin-mcp ready on stdio","version":"0.1.0","tools":11,"dryRun":false,"readOnly":false,"headless":false}

That is a healthy server, not a hang. An MCP stdio server is not a daemon with a port and not a CLI that prints a result and exits. It reads JSON-RPC requests from stdin and writes responses to stdout, so after announcing itself it blocks waiting for a client to say something. With no client attached, there is nothing to say, and a correct server stays quiet rather than printing anything to stdout — one stray byte there would desynchronize the protocol framing.

So: npm start is not how you use this. Register the server with an MCP client (below) and let the client spawn it. If you want to prove it responds while it is sitting there, paste a request into its stdin and press Return — a tools/list reply should come straight back:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/server.js --dry-run

Press Ctrl-C to stop a hand-started server. It shuts down on SIGINT/SIGTERM and logs shutting down.

Two related symptoms:

• Your client shows 0 tools, or "server failed to start". Almost always the path in args is wrong or dist/ was never built. Use an absolute path to dist/server.js, run npm run build, and check your client's own MCP log — the server's stderr ends up there, and config_invalid or a Node module-resolution error will be sitting in it.

• You see the ready line but every tool fails. Check what that line says. dryRun:true means fixtures only, and nothing you do will reach LinkedIn; not_authenticated on every call means there is no saved session yet, so run linkedin_login.

Error codes

Failures come back as MCP tool errors carrying a stable code. The ones you are most likely to see:

verification_required — LinkedIn has put up a CAPTCHA, a checkpoint, or an authwall. The server stops here on purpose and will never try to solve it. Open linkedin.com in your normal browser, clear the challenge as yourself, then run linkedin_login again. If this keeps happening, treat it as a signal to lower your daily caps.

session_expired — the saved session no longer authenticates, or LinkedIn redirected the feed to its sign-in page. Run linkedin_login and sign in by hand again. linkedin_session_status will show you the specific reason.

selector_not_found — the server could not find an element it needed. This almost always means LinkedIn changed its markup, not that you did anything wrong. Every DOM selector in the project lives in src/selectors.ts, which is the single maintenance point: find the relevant candidate list, add a new selector to the front of it, and rebuild. Candidates are ordered lists, so an added selector does not break the old ones. Running with --log-level debug tells you which lookup failed.

rate_limited — you have hit a daily cap. The error and the quota block tell you which one and when it resets (next local midnight). Wait it out, or raise that cap in config.json — but raising a cap is exactly the behaviour that gets accounts restricted, so raise it deliberately.

external_application — the job posting hands applicants off to an external applicant-tracking system rather than LinkedIn's Easy Apply form. The server will not fill in third-party sites. Open the job in a browser and apply there.

not_connected — you tried to message someone who is not a 1st-degree connection. Send a connection request first, wait for it to be accepted, then message. The server will not work around this with InMail.

read_only_mode — the server was started with --read-only (or LINKEDIN_MCP_READ_ONLY=1, or "readOnly": true) and you called one of the four write tools. Nothing was attempted; the refusal happens before the tool runs. Restart without the flag to allow writes. See Read-only mode.

Other codes you may encounter: not_authenticated (no session on disk yet — run linkedin_login), not_easy_apply, invalid_input, confirmation_mismatch (arguments changed between preview and confirm — preview again), navigation_failed, browser_error, dry_run_unsupported, config_invalid (a malformed config.json, reported before the server starts), and file_not_found.

What this does NOT do

• No InMail. Messaging is 1st-degree connections and existing conversations only.

• No external-ATS applications. Easy Apply only; anything that leaves LinkedIn is refused.

• No CAPTCHA solving. No 2FA automation, no checkpoint bypass, ever.

• No multi-account support. One saved session, one account, one person at the keyboard.

• No remote media upload. The server never fetches a URL to attach to a post.

Security & privacy

What is stored, and where. Everything lives on this machine, under the state directory — by default <cwd>/.linkedin-mcp/, overridable with LINKEDIN_MCP_STATE_DIR (or per-path with LINKEDIN_MCP_STORAGE_STATE, LINKEDIN_MCP_USER_DATA_DIR, LINKEDIN_MCP_SCREENSHOT_DIR, LINKEDIN_MCP_COUNTERS):

Nothing is transmitted anywhere. There is no telemetry, no analytics, no crash reporting, and no phone-home of any kind. The only network destination is linkedin.com, reached through your own browser session — and under --dry-run not even that.

Screenshots are local-only. They are written to the screenshots directory for your own debugging and are never uploaded or included in tool output.

Logging is deliberately thin. Diagnostics go to stderr. Cookies, storageState contents, and resume file contents are never logged or serialized. Tool failures log the error code rather than the arguments, so a message body or a resume path cannot leak into a client's captured stderr. redactConfig strips absolute paths (and your home directory) out of the effective-configuration line the server logs at startup.

Gitignore guarantees. .gitignore excludes .env and .env.* (keeping .env.example), the whole .linkedin-mcp/ state directory, storageState.json at any depth, chromium-profile/, counters.json, screenshots/, *.log, plus node_modules/, dist/, and coverage/. Only config.example.json and your config.json stay tracked, and they contain nothing but caps and timeouts. Never commit storageState.json — it is a live credential.

Treat the state directory as a secret. Anyone who can read storageState.json can act as you on LinkedIn without a password or a 2FA code. If you think it has been exposed, sign out of all sessions from LinkedIn's own security settings, delete the file, and log in again.