linkedin-mcp-tools

🔗 LinkedIn MCP

LinkedIn for AI assistants — structured data via a real, stealth browser session

Give Claude, Cursor, and any MCP client access to LinkedIn — profiles, people/job/company search, feed, messaging, and your network — as clean structured JSON.

22 tools · reads + gated writes (connect, message, post, react, comment) · a real safety layer (daily caps, human pacing, circuit breaker) · 166 tests.

⚠️ Automating LinkedIn violates its User Agreement and can get an account restricted. No tool is ban-proof — and this one says so up front. Use a secondary account; read Account safety and DISCLAIMER.md first.

Why this exists

LinkedIn's internal Voyager API (the one its own web app uses) returns rich, structured JSON — but it sits behind Cloudflare bot-management, which rejects plain HTTP requests (a stateless fetch or curl gets stuck in an endless redirect, even with a valid cookie). The only reliable way to read LinkedIn data programmatically in 2026 is from inside a real browser that clears the challenge.

This project's approach:

• Drive a real Chrome via patchright (an undetected Playwright fork) so Cloudflare's challenge is solved with a genuine browser fingerprint.
• Query Voyager from inside the authenticated page — same-origin, the exact network path LinkedIn's own SPA uses → structured JSON, not scraped DOM text.

That last point is the edge over DOM-scraping tools: in-page API calls are locale-independent and resilient to UI redesigns, so they don't break on a moved CSS selector or a translated label.

✨ What's good here

🧩 Structured JSON	In-page Voyager API calls return normalized data, shaped into compact objects — not brittle innerText scraping.
✍️ Writes are API calls, not button-clicking	connect / message / post / react / comment POST straight to Voyager — the exact requests the web app sends, captured and verified live. No hunting for a "Connect" button under a sticky navbar, no composer-dialog race. Every write returns a structured status (ok / duplicate / already_connected / restricted / quota_exhausted / …) — never a blind "sent: true".
🛡️ Safety layer built in	Serial queue, human-paced jittered delays, per-action daily budgets, account warmup ramp, and a circuit breaker that hard-stops on any checkpoint/captcha. (Risk reduction — not a safety guarantee.)
🔥 One warm session	A single persistent browser per process (cookies + Cloudflare clearance survive restarts). Explicit close_session, signal-handled teardown — no zombie Chrome.
🌍 Locale-independent	API + embedded-JSON parsing, not English-only DOM selectors — survives UI redesigns and translations.
🔒 Local & private	Session stored under ~/.linkedin-mcp/ with 0700/0600 perms; no cookies/tokens to paste, none ever logged.

How it compares

	DOM-scraping LinkedIn MCPs	This
Reads	scraped page text (brittle, locale-bound)	structured API JSON
Writes (connect/message/post)	click rendered buttons (break on sticky navbars, dialog races, localized labels)	direct Voyager POST, captured + verified live
Write feedback	"clicked it" → hope	structured status (ok / duplicate / restricted / quota_exhausted / …)
Resilience	breaks on UI tweaks / translations	API + embedded-JSON, locale-proof
Safety (caps, pacing, circuit breaker)	none	✅ built-in, 166 tests
Zombie browser processes	common	✅ reaped on close
Language	Python	TypeScript + official MCP SDK

We hit LinkedIn's own API from inside the challenge-passed browser — reads and writes — so you get the structured response and a real status, not parsed HTML and a hopeful click. (Shipping checklist + launch notes: LAUNCH.md.)

📦 Status

Full transparency — exactly where every piece stands (and what's still alpha):

Area	State
Stealth browser engine (patchright)	✅ built, live-proven
In-page Voyager fetch (the core mechanism)	✅ live-verified (returns structured JSON)
Safety layer (queue / pacer / budgets / circuit-breaker)	✅ built, 166 unit tests
Profile — get_profile, get_my_profile (name, headline, summary, experience, education, skills, certifications, languages)	✅ live-verified
Feed / notifications — get_feed, get_notifications	✅ live-verified
Jobs / messaging — search_jobs, get_job_details, get_inbox, get_conversation	✅ live-verified
People / companies — search_people, search_companies, get_company, get_company_posts, get_company_employees (DOM fallback)	✅ live-verified
Network — get_pending_invitations (received + sent)	✅
Session — whoami, health_check (live Voyager probe + budget headroom), close_session	✅
Write tools — connect_with_person, send_message, create_post, react_to_post, comment_on_post	✅ all 5 endpoints captured + live-verified on a burner; gated (confirm:true + daily caps), structured statuses. Still ⚠️ alpha — these take real, often irreversible actions; use a throwaway account.

22 tools. typecheck + 166 tests green.

Login is headful, the server is headless. The one-time --login opens a real Chrome window (to clear Cloudflare and let you solve any captcha/2FA). After that the persistent profile carries the clearance, so the server runs headless — verified returning live data. Use a residential IP; datacenter/VPN IPs are often pre-flagged by Cloudflare regardless of headless vs headful.

🚀 Quick start

1. Log in once (opens a real Chrome window — sign in, solve any captcha/2FA):

npx -y linkedin-mcp-tools@latest --login

Needs Google Chrome installed (or run npx patchright install chrome once). Your session — Cloudflare clearance and all — persists to ~/.linkedin-mcp/profile/.

2. Point your MCP client at it. Claude Desktop / Cursor / Claude Code config:

{
  "mcpServers": {
    "linkedin": {
      "command": "npx",
      "args": ["-y", "linkedin-mcp-tools@latest"]
    }
  }
}

Then just ask: "Get my LinkedIn profile and summarize my experience" or "Find 5 recruiters at Google."

From source / contributing

git clone https://github.com/devag7/linkedin-mcp.git
cd linkedin-mcp
npm install
npm run setup:browser     # installs the Chrome patchright drives
npm run login             # log in once
npm run spike             # verify: fetches your profile as JSON
npm run build             # produces dist/

MCP config: "command": "node", "args": ["/absolute/path/to/dist/index.js"].

Headless / server deployment

The one-time --login needs a window; the server then runs headless (verified returning live data). Run --login on a machine with a display (or via VNC), copy ~/.linkedin-mcp/profile/ to your server, and run there:

LINKEDIN_HEADLESS=true npx -y linkedin-mcp-tools@latest   # no display needed

Use a residential IP — datacenter/VPN IPs are frequently pre-flagged by Cloudflare regardless of headless vs headful.

🛡️ Account safety

Read this. Automating LinkedIn violates its User Agreement and can get your account restricted or banned — no tool can prevent that, including this one. The built-in safety features (daily caps, human pacing, warmup, circuit breaker) reduce risk; they do not eliminate it.

Defaults err conservative:

• Connections 20/day, messages 50/day, likes+comments 50/day combined, follows 30/day — combined write cap 150/24h.
• Profile views 80/day, searches 30/day.
• New-account warmup ramp over the first weeks; pending-invite ceiling and acceptance-rate pauses.
• Reads paced 4–12s apart, writes 45–150s, with long breaks and a working-hours gate.
• A circuit breaker stops automatically on any checkpoint, captcha, or "unusual activity" page — and never tries to solve one.

Recommendations: use a secondary/throwaway account, run from a residential IP, warm it up slowly. See DISCLAIMER.md for the full legal/ToS notice.

⚙️ Configuration

Variable	Default	Description
LINKEDIN_HEADLESS	true	Server runs headless. --login always opens a real window regardless. Set false to watch the browser.
LINKEDIN_CHROME_PATH	—	Explicit Chrome binary path (else patchright's).
LINKEDIN_PROFILE_DIR	~/.linkedin-mcp/profile	Persistent browser profile.
LINKEDIN_IDLE_TIMEOUT_MS	300000	Close the browser after this idle time (0 disables).
LINKEDIN_CONCURRENCY	1	Serial by default; >1 is ban-risky.
TRANSPORT	stdio	stdio (primary) or http.

🛠 Development

npm run dev          # run from source (stdio)
npm run typecheck
npm test             # vitest (safety layer + smoke)
npm run build

📄 License

MIT — see LICENSE. Not affiliated with LinkedIn. Use at your own risk; see DISCLAIMER.md.

Made by Dev Agarwalla