LinkedIn MCP

A local Electron desktop app that drives LinkedIn through a real, Playwright-controlled Chromium browser and exposes that automation to Claude Desktop (or any MCP client) as an MCP server over stdio.

Instead of using LinkedIn's (restricted) official API, the app logs in as you in a real browser window, keeps the session alive on disk, and lets an AI assistant call a small set of well-defined tools (view a profile, search people/jobs/companies, send a message, send a connection request, read the feed and notifications, etc.). You stay in control: login is manual and headed, so you complete any 2FA/captcha yourself, and your password is never stored.

Heads-up / status: this repository currently has a number of wiring bugs between the Electron main process and the driver/MCP layers (mismatched import paths, method names, and constructor signatures). See the "Known issues" section at the bottom. The README below describes the intended design and usage.

What it does

• Headed, persistent browser session. Launches one Chromium via chromium.launchPersistentContext() with an on-disk profile, plus a portable storageState snapshot for fast validation and recovery.
• Control panel UI. An Electron window shows driver/session status, a sign-in panel, an MCP-client indicator, and a live activity log. The app also lives in the system tray and keeps running in the background as an MCP server.
• MCP server over stdio. Exposes LinkedIn actions as MCP tools so Claude Desktop can call them. All diagnostics go to stderr so the JSON-RPC stream on stdout stays clean.
• Rate-limit-aware automation. Every state-changing action is paced (>= ~2s with jitter) and selectors prefer ARIA/data-*/semantic anchors over LinkedIn's randomized CSS classes.

Quick start (npx)

No clone required — run the MCP server straight from npm:

npx -y @mehmoodqureshi/linkedin-mcp

The first install downloads Playwright's Chromium automatically (via the postinstall hook). The server speaks MCP over stdio, so it's normally launched by an MCP client rather than by hand — add it to your client config (see Connecting to an MCP client). On first use, call the linkedin_login tool: a headed Chromium window opens so you can sign in (and clear any 2FA/captcha) once; the session is then persisted under ~/.linkedin-mcp for future runs.

npx -y @mehmoodqureshi/linkedin-mcp --help      # usage + config snippet
npx -y @mehmoodqureshi/linkedin-mcp --version

The same package also ships the optional Electron desktop control panel (tray + activity log) — see How to run to build it from source.

Prerequisites

• Node.js 20+ (the project targets ES2022 / modern Electron).
• npm (ships with Node).
• Playwright's Chromium browser. Installed automatically by the postinstall script, or manually:

npx playwright install chromium

Install dependencies:

npm install

This also runs playwright install chromium via the postinstall hook.

How to run

Just want the MCP server? Use the npx quick start. This section covers the optional Electron desktop app, built from a source checkout.

npm start

This launches the Electron control panel (UI mode). From there you can:

1. Start Driver – launches the persistent Chromium.
2. Sign In – opens LinkedIn's login page in the controlled browser. Enter your credentials and complete any 2FA/captcha manually in that window. Once you reach the feed, the session is persisted.
3. Watch the Session panel flip to authenticated and the Activity Log for progress.

To rebuild the compiled output (main + renderer) without packaging:

npm run build       # tsc for main/driver/mcp + renderer + copy index.html
npm run typecheck   # type-check only, no emit

Packaging (requires the missing assets/ and build/ files, see Known issues):

npm run pack        # unpacked build
npm run dist        # platform installer(s)

Connecting to an MCP client

MCP clients discover servers from a JSON config — for Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\\Claude\\claude_desktop_config.json

(Claude Code: claude mcp add; other clients use the same command/args shape.)

Recommended — npx (no checkout)

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

Optional env overrides: LINKEDIN_MCP_USERDATA (data/profile dir, default ~/.linkedin-mcp) and LINKEDIN_HEADLESS=1 (run Chromium headless — but keep it headed for the first login).

Alternative — Electron desktop app (from a source checkout)

Runs the same MCP server embedded in the tray app, so you get a control-panel window alongside it:

{
  "mcpServers": {
    "linkedin": {
      "command": "./node_modules/.bin/electron",
      "args": ["."],
      "cwd": "/absolute/path/to/linkedin-mcp",
      "env": { "LINKEDIN_MCP_STDIO": "1" }
    }
  }
}

Notes:

• Restart the client after editing the config.
• Both paths share the same persistent session on disk, so logging in once via either is enough.
• The MCP server keeps stdout reserved for JSON-RPC; all diagnostics go to stderr.

MCP tools

All tools are namespaced linkedin_*. Auth/status tools work without being logged in; every data/action tool requires an authenticated session (call linkedin_login first).

| Tool | Arguments | Description | | --- | --- | --- | | linkedin_login | email?, password? | Opens the headed login flow. Optionally pre-fills credentials; you finish 2FA/captcha by hand. Waits for the session, then persists it. The password is never stored. | | linkedin_logout | – | Clears the saved storageState snapshot and the profile cookies; next action needs a fresh login. | | linkedin_status | – | Returns { status, isLoggedIn, sessionValid }. Works before the browser is launched. | | linkedin_get_profile | profileUrl (full URL or /in/ slug) | Opens and scrapes a member profile: name, headline, location, about, experience, education, skills, connection count. | | linkedin_search_people | query, filters? | People search; returns name, headline, location, profile URL, connection degree. | | linkedin_search_jobs | query, filters? | Jobs search; returns title, company, location, posted date, easy-apply, job URL. | | linkedin_search_companies | query, filters? | Company search; returns name, industry, followers, company URL. | | linkedin_send_message | profileUrl, message | Sends a DM to a 1st-degree/open-profile member. Fails clearly if messaging isn't permitted. | | linkedin_send_connection | profileUrl, note? (<=300 chars) | Sends a connection request, optionally with a note. Returns outcome: sent / already_sent / already_connected / unavailable. | | linkedin_get_feed | limit? (1–50, default 10) | Reads home-feed posts: author, text, timestamp, like/comment counts, post URL. | | linkedin_get_notifications | limit? (1–50, default 20) | Reads notifications: type, actor, text, timestamp, URL, read/unread. | | linkedin_get_conversations | – | Lists inbox threads: participant, snippet, conversation id, timestamp, unread state. |

Each tool returns a JSON payload inside the standard MCP text-content envelope. On failure the result carries isError: true with an actionable message (e.g. "Not logged in to LinkedIn. Run linkedin_login…").

The advertised filters schemas for the search tools are richer than the filters the driver currently applies; treat advanced filters as best-effort for now (see Known issues).

Session persistence

Two cooperating layers keep you logged in across restarts:

1. Persistent Chromium profile (primary). The browser runs against an on-disk profile directory (<userData>/playwright-profile). Cookies, localStorage, and IndexedDB live there and survive app restarts on their own — exactly like a normal browser that "remembers" you.

2. Portable storageState snapshot (secondary). On login (and on graceful close) the app also writes <userData>/linkedin-session.json. This gives:

   • a fast, browser-free "am I logged in?" check by inspecting the LinkedIn li_at cookie and its expiry (no Chromium launch required), and
   • a recovery path: if the profile is corrupted, a fresh context can be re-hydrated by re-injecting the snapshot's cookies via context.addCookies(...).

<userData> is Electron's per-app data directory (e.g. ~/Library/Application Support/LinkedIn MCP/ on macOS). Outside Electron it falls back to $LINKEDIN_MCP_USERDATA or ~/.linkedin-mcp.

Validity is determined by the presence of a non-expired li_at cookie. A session cookie (expires === -1) is treated as valid. linkedin_status / the UI surface this as sessionValid, while isLoggedIn additionally confirms against the live page when a context is up.

Logging out (linkedin_logout / the Logout button) clears the profile cookies and deletes the snapshot, forcing a fresh manual login next time.

The session files contain live credentials-equivalent cookies — .gitignore already excludes userData/, pw-profile/, and any storageState.json. Never commit a logged-in session.

Configuration (.env)

Copy .env.example to .env. All values are optional:

• LINKEDIN_EMAIL / LINKEDIN_PASSWORD – optional pre-fill for auto-login. Not recommended; manual headed login is preferred and required for 2FA/captcha accounts.
• MCP_LOG_LEVEL – error|warn|info|debug|trace.
• LINKEDIN_MCP_STDIO – set to 1 when launched by Claude Desktop as a stdio MCP server (the config injects this).
• PLAYWRIGHT_BROWSERS_PATH – override the Playwright browsers location (packaged builds point this at the bundled Chromium).

Project layout

src/
  main/        Electron main process: lifecycle, window, tray, IPC, bootstrapping
    index.ts
    ipc-handlers.ts
  preload/     Context-isolated bridge exposed as window.linkedinMCP
    index.ts
  driver/      Playwright automation layer
    browser.ts     BrowserManager (persistent context, singleton)
    session.ts     SessionManager (storageState persist/validate/recover)
    linkedin.ts    LinkedInDriver facade (composes the action modules)
    types.ts       Shared normalized result types
    actions/       auth, profile, search, messages, connections, feed (+ common, index)
  mcp/         MCP server + tool catalog/dispatch
    server.ts
    tools.ts
    claude-desktop-config.ts
  renderer/    Control-panel UI (sandboxed, no Node)
    index.html
    app.ts

Known issues

This codebase does not yet build/run cleanly. The main process, the driver facade, and the MCP/IPC layers were written against slightly different APIs. The most important mismatches:

• Wrong import paths in src/main. index.ts and ipc-handlers.ts import ./driver/PlaywrightDriver and ./mcp/server, but the real files are ../driver/linkedin and ../mcp/server. There is no PlaywrightDriver file or createDriver export (use getInstance() / LinkedInDriver).
• linkedin.ts imports ./actions/messaging but the file is actions/messages.ts.
• Driver facade vs. main process contract drift: the main process treats the driver as an EventEmitter (driver.on('status', …)) and reads getStatus().state, neither of which the driver provides (getStatus() returns { status, isLoggedIn, sessionValid }).
• MCP server API: index.ts imports getMcpStatus and calls startMcpServer({ driver, transport }), but server.ts exposes no getMcpStatus and startMcpServer() takes no arguments.
• IPC handler method names don't match the action modules: e.g. profile.view (should be getProfile), search.people/jobs/companies(query, page) (should be searchPeople/searchJobs/searchCompanies(query, filters?)), connection.sendRequest (should be connections.sendConnectionRequest), message.send (should be messages.sendMessage), notifications.list (should be feed.getNotifications), feed.read (should be feed.getFeed), and auth.login({email,password}) (should be login(email, password)).
• AuthActions constructor mismatch: linkedin.ts builds new AuthActions(page, session, {email,password}), but the constructor is (page, paths?).
• tsconfig.json path aliases point at non-existent src/main/driver, src/main/mcp, src/shared.
• Packaging assets missing: electron-builder.json references assets/icon.*, build/entitlements.mac.plist, and node_modules/playwright-core/.local-browsers (the project installs playwright, not playwright-core); package.json's register-mcp script points at a non-existent scripts/register-mcp.ts.
• (Resolved) MCP mode detection: the Electron entry now keys off LINKEDIN_MCP_STDIO=1 / --mcp / a non-TTY stdout, matching the config above. The standalone npx binary (dist/cli.js) needs no such flag — it is always an MCP stdio server.

Reconcile these before expecting npm run build / npm start to succeed.

Disclaimer

Automating LinkedIn may violate its Terms of Service and can lead to rate limiting or account restriction. Use a real, consenting account, keep volumes low, and run this only for personal, lawful purposes. You are responsible for how you use it.