linkedin-agent-mcp

A personal, human-in-the-loop LinkedIn job-search agent, exposed as an MCP server so an MCP client such as Claude Code can search jobs, read postings and your profile, track what you have seen, and prepare actions, while every consequential step on LinkedIn requires your explicit confirmation, given out-of-band in your own terminal.

It is deliberately not a mass-automation or scraping system: one browser page at a time, small capped result sets, spaced navigation, an hourly cap on external actions, and no evasion techniques of any kind.

At a glance

• What it is: a TypeScript (Node 24) MCP server with 20 typed tools that let an AI agent search jobs, read postings and your profile, track what you have seen, and prepare actions on your own LinkedIn account.

• Ports and adapters: the MCP layer is thin (zod schemas + error mapping); services depend on a LinkedInClient interface and repository interfaces, so Playwright lives in exactly two files and SQLite sits behind swappable repositories.

• READ / PREPARE / EXECUTE, enforced structurally: each tool group is handed only the ports it may use, so a READ or PREPARE tool cannot reach the executor, not by prompt instructions but by construction.

• Out-of-band confirmation: there is no confirm tool. Every external action needs a human to run npm run confirm in a real terminal and type a code; the payload is SHA-256 bound to that approval, single-use (database compare-and-swap), and time-limited.

• Failure-honest: ambiguous writes become OUTCOME_UNKNOWN and are never auto-retried; LinkedIn markup changes surface as a typed LINKEDIN_CHANGED, never as made-up data; the audit log is append-only via database triggers.

• Tested: 199 vitest tests (parsers on captured/modelled fixtures, state machines, the whole confirmation workflow including tampering and races, and a spawned stdio server through the real MCP SDK client), plus an opt-in read-only E2E suite run against a real account.

• Documented decisions: 13 ADRs in docs/decisions/.

Status (2026-09-23): read-only flows (auth, search, job detail, own profile, saved jobs) are verified live on a real signed-in account, and so is the one registered write, Save/Unsave, run once end to end through the terminal confirmation with the owner present. Easy Apply, messaging, connections and profile writes are not implemented yet. Details in Verification status and CLAUDE.md.

Read this first: ToS and status. LinkedIn's User Agreement (§8.2) prohibits bots and other automated access. There is no official LinkedIn API for job search, saved jobs or applications for job seekers (see LinkedIn API limitations). This project drives a real browser on your own account. That is a risk to your account that only you can accept, and the browser will not start until you have (npm run login). Also see Verification status: parts are verified live, parts are only unit-tested.

Contents

Architecture · Why MCP · Stack · READ / PREPARE / EXECUTE · Security model · Install · Authentication · Configuration · Claude Code · Tools · Confirmation · Application workflow · Persistence · Testing · Verification status · Limitations · Roadmap · Responsible use · Decision log

Related MCP server: linkedin-mcp-server

Architecture

flowchart TB
    CC["Claude Code / MCP client"] -->|"stdio JSON-RPC"| MCP["MCP server (thin: schemas, kind labels, error mapping)"]

    subgraph tools["Tool groups get only the ports they may use"]
        R["READ tools"]
        P["PREPARE tools"]
        E["EXECUTE tools (actionId only)"]
    end
    MCP --> R & P & E

    R --> JS["JobService / ProfileService"]
    P --> JS
    P --> AP["ActionPreparer"]
    E --> AX["ActionExecutor"]

    AX --> AS["ActionService<br/>state machine, hash check, CAS, audit"]
    AP --> AS
    JS --> LC["LinkedInClient (interface)"]
    AS -->|"executors"| LC

    LC --> BC["Browser client (Playwright)"]
    LC -.->|"future: official API where one exists"| API["LinkedIn API"]
    BC --> BM["BrowserManager<br/>persistent profile, 1 page, throttled, linkedin.com only"]
    BM --> LI[("linkedin.com")]

    JS & AS & AP --> REPO["Repository interfaces"] --> DB[("SQLite<br/>jobs · job_views · applications · application_answers<br/>profile_changes · messages · actions · audit_events")]

    HUMAN(["You, in a terminal"]) -->|"npm run confirm (TTY + typed code)"| CF["ConfirmationService"] --> AS

Rules the layout enforces:

• The MCP layer is thin. Tools validate input (zod), call a service, and map errors. No business logic, no SQL, no Playwright.

• Services depend on interfaces. LinkedInClient hides how LinkedIn is reached; repositories hide where state lives.

• Only two files import Playwright: src/browser/browser-manager.ts (site-agnostic) and src/linkedin/browser-client.ts (LinkedIn-specific). All DOM knowledge is in src/linkedin/selectors.ts; parsing is pure functions in src/linkedin/parsers/.

• The confirmation port is not reachable from MCP. See Confirmation workflow.

src/
  index.ts  server.ts  container.ts  config.ts  logger.ts  consent.ts  state-machine.ts
  browser/      browser-manager.ts               persistent context, serialization, throttling, allowlist
  linkedin/     linkedin-client.ts (interface) browser-client.ts session.ts url.ts selectors.ts types.ts
                parsers/ (search, job, profile, dom)
  jobs/ profile/ messaging/ applications/ actions/   services + state machines
  persistence/  database.ts migrations.ts repositories/
  tools/        define.ts schemas.ts views.ts  read/ prepare/ execute/
  cli/          login.ts confirm.ts
  errors/       errors.ts
docs/decisions/ 13 ADRs + index + template        scripts/decisions.mjs
tests/ fixtures/

Why MCP

MCP gives an agent typed, discoverable tools over a standard protocol, so the same server works with Claude Code today and other clients later. It also gives a natural place to put the safety model: the tool surface (what exists, what each accepts) is part of the security boundary. There is no confirm tool, and execute tools accept only an actionId.

Why this technology stack

Four runtime dependencies in total. Logging and state machines are hand-rolled on purpose.

READ / PREPARE / EXECUTE

This is enforced structurally (interfaces handed to each group, state machine, database), not by prompt instructions. The prompt-level guidance in the server instructions is only a courtesy on top.

Security model

Threat model: an LLM (possibly manipulated by hostile text in a job posting) acting only through MCP tools and non-interactive shell, on a machine you control. Out of scope: malware or a person with full access to your account/machine (they could edit the SQLite file or read your browser profile).

Defence in depth: .claude/settings.json adds Claude Code ask rules for the execute tools.

Installation

Requirements: Node.js ≥ 24, and Google Chrome or Microsoft Edge installed (or npx playwright install chromium and BROWSER_CHANNEL=chromium).

git clone <this repo> linkedin-agent-mcp && cd linkedin-agent-mcp
npm install
npm run build
npm test

Authentication

npm run login

1. First run only: shows the ToS/automation notice; you must type I UNDERSTAND. (Refuses to run without an interactive terminal.)

2. Opens a visible Chrome/Edge window on a dedicated profile (~/.linkedin-agent-mcp/browser-profile).

3. You sign in: password, MFA, and any CAPTCHA (the program never automates or bypasses these).

4. It detects the session (presence of the li_at cookie and a non-wall page), double-checks by loading the feed, and closes the browser so the profile is saved.

Re-run when the session expires (LOGIN_REQUIRED). Check state any time with the linkedin_auth_status tool.

Configuration

Typed and validated at startup (src/config.ts); see .env.example. No LinkedIn credentials exist in configuration.

npm run confirm reads the same variables. If you override LINKEDIN_AGENT_HOME/DATABASE_PATH for the MCP server, set them in your shell too, or the CLI will look at a different database.

Claude Code integration

Syntax verified against the current Claude Code docs (claude mcp add [options] <name> -- <command> [args...]; options go before the name; -- is mandatory).

Option A: command line (use absolute paths; build first with npm run build):

# Windows example
claude mcp add --scope user linkedin-agent -- node C:\Users\you\code\linkedin-agent-mcp\dist\index.js
# macOS/Linux
claude mcp add --scope user linkedin-agent -- node /home/you/linkedin-agent-mcp/dist/index.js

--scope local (default) = this project only, private; --scope project = writes .mcp.json; --scope user = all your projects. node is invoked directly, so the cmd /c wrapper (needed for npx on native Windows) is not required.

Option B: .mcp.json: a ready-made one is in this repo (works when Claude Code is opened in this folder; the first time it asks you to approve the project server):

{
  "mcpServers": {
    "linkedin-agent": {
      "command": "node",
      "args": ["dist/index.js"]
    }
  }
}

The path is relative on purpose: stdio servers start in the project folder, and ${CLAUDE_PROJECT_DIR} is not expanded in .mcp.json (Node received the literal text and exited, which showed up as CONNECTION_CLOSED; the real error is in %LOCALAPPDATA%\claude-cli-nodejs\Cache\<project>\mcp-logs-linkedin-agent). Run npm run build first, and restart the session (or /mcp → Reconnect) after changing this file.

For use from other projects, put an absolute path in args, or use Option A with --scope user. Verify with claude mcp list, or /mcp inside a session. To debug interactively: npm run inspect (MCP Inspector).

Recommended permissions (.claude/settings.json is included). Keep the execute tools on ask, never allow:

{ "permissions": { "ask": ["mcp__linkedin-agent__linkedin_save_job", "mcp__linkedin-agent__linkedin_unsave_job"] } }

Available tools

Every description is prefixed with its kind. Full schemas are visible via tools/list.

READ

PREPARE (local state only)

EXECUTE (requires a user-confirmed action)

Planned, not registered so the agent never meets a dead end: submit_application, update_profile, send_message, send_connection_request, prepare_application. See ADR-0009.

Example

// 1. agent → linkedin_search_jobs
{ "keywords": "NestJS", "location": "Tel Aviv, Israel", "workType": "hybrid", "maxResults": 5, "onlyNew": true }
// ← { "jobs": [{ "id": "3812345678", "title": "...", "company": "...", "isNew": true, "localStatus": "discovered", ... }],
//     "fetched": 5, "newCount": 3, "filteredOut": 2 }

// 2. agent → linkedin_prepare_save_job   { "url": "https://www.linkedin.com/jobs/view/3812345678/" }
// ← { "action": { "actionId": "26751bd3-…", "status": "PENDING", "preview": "SAVE \"…\" at … on LinkedIn" },
//     "executionAvailable": true, "nextStep": "Show the preview… run `npm run confirm -- 26751bd3`…" }

// 3. YOU, in a terminal:  npm run confirm -- 26751bd3      (shows the preview, asks you to type a code)

// 4. agent → linkedin_save_job { "actionId": "26751bd3-…" }   ← COMPLETED (single use)

Confirmation workflow

prepare tool ─► PENDING ──(you: npm run confirm, TTY + code)──► CONFIRMED ──► EXECUTING ──► COMPLETED
     │             │ ▲                                              │            │ ├─► FAILED           (proven: nothing happened)
     │             │ └── payload hash fixed here                    │            │ └─► OUTCOME_UNKNOWN  (ambiguous: never auto-retry)
     │             └─► CANCELLED / EXPIRED                          └─► CANCELLED / EXPIRED (10 min)
     └─ returns actionId + exact preview

• Why out-of-band? The agent calls the tools, so any in-band confirmed:true can be forged. See ADR-0004.

• npm run confirm (list) · npm run confirm -- <id> (review + confirm) · -- --cancel <id> · -- --audit <id> · -- --resolve <id> completed|failed (after an OUTCOME_UNKNOWN, once you have checked LinkedIn).

• "Apply to good jobs", "go ahead with all of them", or any vague instruction is not a confirmation: each action needs its own confirmation of its exact payload.

Application workflow

Target flow: search → inspect → analyze → prepare_application → (needs_user_input | ready_to_submit) → your review → your confirmation → submit_application.

Implemented today: the guarded core: ApplicationService and the application state machine (DISCOVERED → PREPARING → NEEDS_USER_INPUT ⇄ READY_TO_SUBMIT → CONFIRMED → SUBMITTING → SUBMITTED, plus FAILED, SUBMISSION_UNCERTAIN, EXTERNAL, ABANDONED), with these rules enforced and tested: answers are never fabricated (unknown ⇒ needs_input); READY_TO_SUBMIT is impossible with open questions; external applications are detected and reported, never auto-submitted; SUBMITTED is terminal; an uncertain submission can only be resolved, never retried; the preview format (Job / Company / Position / CV / fields / questions / final action) is built by buildPreview. The user-input-collection + preview half of the tool surface is registered (linkedin_get_application, linkedin_provide_application_answer, linkedin_preview_application, 2026-09-22) — but since nothing yet creates an application with real questions (that is prepare_application, next), these tools have no reachable data on the real account until then; they are unit- and protocol-tested against directly-seeded application state.

Not implemented: the Easy Apply form driver, prepare_application and submit_application. A real signed-in session now exists, but no Easy Apply form has been captured yet; the driver is built from a real, read-only capture of one (see Roadmap), starting with prepare_application, never with submit. They are not exposed as tools.

Persistence

SQLite at ~/.linkedin-agent-mcp/agent.db (WAL). Tables: jobs (unique canonical_key = li:<jobId> for dedupe, first_seen_at, last_seen_at, seen_count, status), job_views, applications, application_answers, profile_changes, messages, actions, audit_events (append-only). Job statuses: discovered, viewed, considering, saved, rejected, preparing, ready_to_submit, submitted, failed, changed only through a transition table. Migrations are forward-only (src/persistence/migrations.ts).

Testing

npm test                       # unit + protocol tests, no network
npm run typecheck
LINKEDIN_E2E=true npx vitest run tests/e2e   # OPT-IN, real account, read-only, see file header

PowerShell: $env:LINKEDIN_E2E="true"; npx vitest run tests/e2e

Profile lock. The E2E suite and the MCP server share one persistent browser profile, and Chrome allows one process per profile. If the MCP server has used the browser recently (any browser-backed tool call, including linkedin_auth_status), the E2E run fails immediately with "Could not start the chrome browser" until the server closes its idle browser (BROWSER_IDLE_CLOSE_MS, default 5 min). Run E2E with the MCP server disconnected, or wait.

Covers: input validation through the real MCP SDK client; job parsing (synthetic and real captured fixtures); job-ID extraction and canonicalisation; deduplication (in the database and in the service); application, action and job state machines (including forbidden transitions such as SUBMITTED → PREPARING); the full confirmation workflow (unconfirmed, expired, wrong type, tampered payload, single-use, race, hourly limit, non-TTY, wrong code); failure classification (FAILED vs OUTCOME_UNKNOWN) and audit trail; error mapping and leak checks; logger redaction; the consent gate; repository behaviour incl. append-only triggers; and a real spawned stdio server proving stdout carries only JSON-RPC.

Verification status

Honest accounting of what has and has not been exercised.

Limitations

• Selectors will break when LinkedIn changes markup. Failure mode is a typed LINKEDIN_CHANGED, never fake data; DEBUG_SNAPSHOTS=true saves the page for a quick fix.

• Signed-out pages are throttled by LinkedIn within a few requests (HTTP 999); the intended mode is signed in.

• The signed-in layout has no <h1>, no stable class names and no <li> in profile lists. It is read through <title>, headings, data-testid and componentkey anchors (ADR-0013); expect these to churn too.

• linkedin_get_profile is slow by design (main page, lazy-load scrolling, up to three "show all" pages, spaced navigation): tens of seconds. Make sure the MCP client's tool timeout allows it.

• The E2E suite and the MCP server cannot use the browser profile at the same time (see Testing).

• In signed-out views an "Apply" button is ambiguous, so easyApply/applyType are reported as unknown.

• One browser page at a time; a search returns at most 25 results by design.

• node:sqlite is still flagged experimental by Node.

• The confirmation model does not protect against something with full shell/database access to your machine.

LinkedIn API limitations

Officially available to any developer: Sign in with LinkedIn (OpenID Connect) and Share on LinkedIn. Job-related APIs (Talent Solutions: Job Posting, Apply Connect, Recruiter System Connect, …) are partner-gated and built for employers/ATS vendors. There is no official API for a job seeker to search jobs, read saved jobs, apply, message, or read their own full profile. LinkedInClient is the seam to swap in an official API if that changes.

Browser automation limitations

Violates LinkedIn ToS §8.2 on its face (see top); subject to bot detection (HTTP 999, CAPTCHA, verification checkpoints: all surfaced as typed errors and never bypassed); DOM churn; sessions expire; needs a real browser installed.

Roadmap

Done: signed-in read-only flows verified live and parsers fixed (2026-09-20, ADR-0013); Chrome-exit-at-launch now classified as a profile lock, not "could not start Chrome" (2026-09-22); get_saved_jobs implemented, unit-tested against a modelled fixture, registered, and verified live by tests/e2e (2026-09-22); user-input-collection + application-preview tools (linkedin_get_application, linkedin_provide_application_answer, linkedin_preview_application) implemented, registered, unit- and protocol-tested (2026-09-22) — built ahead of prepare_application, so not yet reachable on the real account; Save/Unsave verified live end to end with the owner present (2026-09-23).

Next, in order (each gated on live verification, read-only first; the same list with working notes is in CLAUDE.md):

1. prepare_application: open a real Easy Apply form read-only, detect fields/questions, fill only what the profile/CV/config establishes, stop at needs_user_input, detect external apply. This is where the agentic logic starts, and the first thing that will actually feed data into linkedin_get_application/linkedin_provide_application_answer/linkedin_preview_application. Do not start with submit_application.

2. submit_application with idempotency checks (inspect LinkedIn's "Applied" state before any retry).

3. Only then update_profile, send_message, send_connection_request.

Later: richer job tracking (notes, follow-ups); optional MCP elicitation as a second confirmation channel; PostgreSQL repositories if ever multi-user.

Responsible use

This is for your own account and a small number of deliberate actions. Do not use it to mass-apply, mass-message, mass-connect or harvest data. Do not point it at other people's accounts. Do not add stealth, CAPTCHA solving or rate-limit evasion: when LinkedIn says no (999, checkpoint, CAPTCHA), stop. You are responsible for compliance with LinkedIn's terms and applicable law, and for the accuracy of anything submitted in your name. Never let an agent fabricate answers on applications; the design makes it ask you.

Decision log

Every significant choice, with options considered and an interview soundbite: docs/decisions/ · docs/INTERVIEW.md · npm run decisions.

License

MIT. The licence covers this code only; using it against LinkedIn is still subject to their User Agreement (see Responsible use).