linkedin-toolkit

<div align="center">

# LinkedIn Toolkit

[![License: MIT](https://img.shields.io/badge/license-MIT-3da639.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-server-6c5ce7.svg)](docs/agents/README.md)
[![No headless browser](https://img.shields.io/badge/no%20headless%20browser-0ea5e9.svg)](docs/why-browser-agents-fail-on-linkedin.md)
[![Runs locally](https://img.shields.io/badge/runs-locally-16a34a.svg)](docs/architecture.md)
[![CI](https://github.com/OpenRecruiterTools/linkedin-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/OpenRecruiterTools/linkedin-toolkit/actions/workflows/ci.yml)

### LinkedIn blocks AI browser agents. This is how agents get in.

</div>

Operator, Browser Use, computer-use models and Playwright bots get challenged or banned on
LinkedIn: headless fingerprints, datacenter IPs, machine-speed clicks. LinkedIn Toolkit gives any
agent a safe, structured API to **your own logged-in Chrome session** — through the same internal
endpoints the LinkedIn page itself calls, at human pace, under hard caps, with a human approval
queue. It is also a free replacement for Waalaxy and PhantomBuster if you never touch an agent at
all. No headless browser, no proxies, no cloud session, no telemetry, no subscription.

<div align="center">

![LinkedIn Toolkit: ask, search, drafts in a queue, approve](docs/assets/demo-storyboard.png)

<sub>*A 30-second demo GIF replaces this still shortly — see [docs/launch/record-demo.md](docs/launch/record-demo.md).*</sub>

</div>

## Install in 3 lines

```bash
# 1. Get the extension: download linkedin-toolkit-extension-v2.0.4.zip from Releases, unzip it,
#    then chrome://extensions → Developer mode → Load unpacked → pick the folder
# 2. Start the server (it prints a pairing token)
npx linkedin-toolkit-mcp
# 3. Paste the token into the extension popup → Settings → Local bridge
```

Never installed an unpacked Chrome extension before, or only want the extension and not
the agent half? [**docs/install.md**](docs/install.md) walks through it with screenshots,
and shows how to clean up your feed with mass unfollow — Preview first, then a small
number, then the rest. Read the "Connections are followed too" part before you decide
the feature is broken: LinkedIn's Following list does not include your connections,
who are followed automatically when you connect, so emptying that list to zero leaves
a feed still full of posts. Ticking "Also unfollow my connections" scans your
followers list instead, which is the only place that state is visible.

Then point your agent at it. Claude Code, `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "linkedin-toolkit": {
      "command": "npx",
      "args": ["-y", "linkedin-toolkit-mcp"]
    }
  }
}
```

That block works, verbatim, in Claude Desktop, Cursor, Windsurf, Cline and OpenClaw too. Zed,
Codex CLI and Gemini CLI want a slightly different shape — [one page each](docs/agents/README.md).

Not using MCP? `lit serve --http` gives you `POST /actions/{action}` and a generated
`GET /openapi.json`. [Examples in seven languages](examples/).

> [!IMPORTANT]
> **Nothing sends without you.** Copilot mode is the default: every write an agent makes queues
> for your approval in the popup. Hard caps live in the extension — 100 invites, 150 messages, 500
> profile visits, 1,000 search results a day — and no agent, CLI flag or config file can raise
> them. [Read the safety page](docs/safety.md) before you turn Autopilot on.

## What it does

| | |
|---|---|
| **Extract** | Profiles (full page text + photo), search, Sales Navigator, Recruiter, post likers and commenters, group members, event attendees, company employees, your own connections and followers, message threads. CSV, JSON and SQLite out. |
| **Lists and CRM** | Named lists, tags, dedupe across lists, a "contacted before" flag on every profile, and intent signals: engaged with a post, changed job in the last 90 days, at a target company. |
| **Sequences** | Visit, follow, connect with a note, message, InMail, like, comment, wait, and branch on accepted / replied / not accepted after N days. Variables with fallbacks, A/B variants per step, replies stop the sequence. [20 templates](sequences/). |
| **Inbox** | Unified threads, unread, reply detection, sentiment tagging, saved replies, snooze. |
| **Research Pack** | A CSV of names or domains in; a dossier, an enriched CSV and a list out. [Below](#research-pack). |
| **Agent layer** | 39 MCP tools, 4 resources, 3 prompts, a `/actions` HTTP API with OpenAPI 3.1, Node and Python clients, an n8n node, [6 skills](skills/). |
| **Safety** | Jittered human delays, hourly and daily caps, business hours, 14-day warm-up, account presets, approval queue, 429 backoff, 451 challenge auto-pause. |
| **Local everything** | `chrome.storage.local`, IndexedDB and a SQLite file on your machine. Read-only SQL over the lot. No server, no account, no telemetry. |

## Works with your agent

| Ecosystem | How | |
|---|---|---|
| Claude Code, Claude Desktop, Cursor, Windsurf, Zed, Cline, OpenClaw, Codex CLI, Gemini CLI | `npx linkedin-toolkit-mcp` | MCP over stdio · [config per client](docs/agents/README.md) |
| Remote and hosted agents (Claude API MCP connector, ChatGPT connectors, Cloudflare Agents) | `lit serve --http` | MCP over Streamable HTTP, token auth · [risks](docs/agents/chatgpt-connector.md) |
| OpenAI Agents SDK, Vercel AI SDK, LangChain.js, Mastra | `npm i linkedin-toolkit` | Typed client + tool definitions · [example](examples/openai-agents/) |
| LangChain, LlamaIndex, CrewAI, AutoGen, Google ADK, Pydantic AI, smolagents | `pip install linkedin-toolkit` | Python client + `@tool` wrappers per framework · [example](examples/crewai/) |
| n8n, Make, Dify, Flowise | `n8n-nodes-linkedin-toolkit` + MCP client node | Nodes for search, profile, invite, message, inbox, plus a webhook-fed trigger · [workflow](examples/n8n/) |
| Any HTTP agent | `lit serve --http` | `GET /openapi.json` — OpenAPI 3.1 for custom GPTs, Dify and code generators |
| Agent Skills standard | `skills/` | Six skills that load unchanged in Claude Code, OpenClaw, and any compliant runtime |

Structured errors carry `code`, `message`, `retryAfter` and `howToFix`, so an agent recovers or
explains itself instead of retrying into a wall. There is an
[`llms.txt`](llms.txt) and an [agent quickstart](docs/agents/quickstart.md) written for an agent to
read and self-install.

## Browser agents vs LinkedIn Toolkit

|  | Browser agent | LinkedIn Toolkit |
|---|---|---|
| **Session** | Headless or remote-controlled browser, cloud profile | Your own Chrome, your own login |
| **Fingerprint** | Synthetic — patched, and detectable anyway | Your real browser. Nothing to patch |
| **IP** | Datacenter, or a residential proxy of dubious provenance | Your own connection |
| **Detection** | Challenged, degraded, then restricted | No fingerprint or IP delta; volume and rhythm are still visible, which is why the caps exist |
| **What the agent sees** | Screenshots, vision tokens, brittle selectors | Typed JSON per tool |
| **Cost to source 100 profiles** | Hundreds of screenshots | 3 tool calls |
| **Pace** | Machine speed | Jittered human delays, business hours, warm-up |
| **Limits** | None until LinkedIn imposes them | Hard caps no client can raise |
| **On a challenge** | Retries, and makes it worse | Stops everything, tells the human |
| **Human oversight** | Whatever you remember to build | Approval queue, on by default |

The long version, with the actual detection mechanisms:
[**Why browser agents fail on LinkedIn**](docs/why-browser-agents-fail-on-linkedin.md).

## Why extensions broke, and why this one is built to be repaired

LinkedIn's web client now serves nearly all of its data through
`GET /voyager/api/graphql?queryId=<name>.<32-hex hash>&variables=(...)`, and those hashes change
with each web client release (current: 1.13.46474). The old REST Voyager paths that a generation of
2024–2025 extensions hard-coded return 400, 410 or 500 today. That is the mechanism — not a ban
wave. This extension calls the same GraphQL queries the page calls, from inside your own tab, and
keeps every query ID in one refreshable table with its capture date and client version:
[docs/voyager-endpoints.md](docs/voyager-endpoints.md). `lit endpoints check` reports which are ok,
failed or unverified, so drift is a maintenance task rather than an architecture change.

Honestly: those IDs **will** drift, and re-capturing them is the contribution this project most
needs. It is a table edit, not a rewrite — open DevTools on LinkedIn, filter the Network tab for
`voyager/api`, and copy the `queryId` from a request the page makes; the same hashes are also
literal strings inside LinkedIn's JS bundles if you would rather grep for them.

## Versus the paid tools

| | Waalaxy Pro | PhantomBuster Starter | Sales-Mind | **LinkedIn Toolkit** |
|---|---|---|---|---|
| Price | ~€70/mo | ~$69/mo | ~$99/mo | **£0** |
| Source | Closed | Closed | Closed | **MIT, all of it** |
| Where the automation runs | Their cloud *(the extension imports only)* | Their cloud | Their cloud | **Your own Chrome tab** |
| Your session | On their servers | On their servers | On their servers | **Never leaves your machine** |
| MCP server | ✗ | ✗ | ✗ | **✓** |
| Agent tools / SDKs | ✗ | ✗ | ✗ | **✓ 39 tools, 9 frameworks** |
| Local SQL over your data | ✗ | ✗ | ✗ | **✓** |
| Approval queue | ✗ | ✗ | ✗ | **✓ on by default** |
| Sequences with branching | ✓ | partial | ✓ | **✓** |
| Post engagers, groups, events | ✓ | ✓ | partial | **✓** |
| Inbox and sentiment | ✓ | ✗ | ✓ | **✓** |
| Team seats, dashboards | ✓ | ✓ | ✓ | ✗ *(needs a server — see [roadmap](docs/roadmap.md))* |
| Telemetry | ✓ | ✓ | ✓ | **✗** |

<sub>Competitor prices are public list prices checked September 2026 and are approximate — they
change, vary by currency and billing term, and each vendor's tiers differ. Feature claims are taken
from each vendor's public pr