LinkedIn Evidence MCP

An independent, community-built tool. Not affiliated with, endorsed by, or sponsored by LinkedIn Corporation or Microsoft. "LinkedIn" is a trademark of LinkedIn Corporation, used here only to describe the service this software interoperates with.

A local-first LinkedIn workspace with one shared engine and two synchronized ways to use it:

• the stdio MCP server, which is the primary workflow engine for evidence, profile, drafting, analytics, and maintenance;

• an optional loopback dashboard, which is the visual support and human-review surface over the same tools and data.

The application keeps its own SQLite database and artifact store on this computer. It does not contain an LLM, a hosted service, a scheduler, scraping, browser automation, cookie reuse, or automated engagement.

Nothing here refreshes on a timer. LinkedIn data is pulled only when you or an agent invoke a tool that does it. That is a product decision about predictability, not a restriction imposed by LinkedIn's terms — see reading the latest LinkedIn profile.

What it is for

The app turns evidence you control—CVs, documents, repositories, LinkedIn exports, and manually imported history—into:

• a verified claim ledger;

• an evidence-backed canonical profile;

• exact profile change patches for manual copy/paste;

• LinkedIn post drafts with deterministic validation;

• content pillars, opportunities, and a planning calendar;

• publication approvals and an append-only audit history;

• local backups, exports, and retention controls.

External LinkedIn features are optional. They remain unavailable until the corresponding developer-app credential is stored, verified against LinkedIn, and explicitly enabled where required. The rest of the product works without those credentials.

Related MCP server: linkedin-mcp

Requirements

• Windows 10 or later, Linux, or macOS. All three are supported and all three run the full test suite on every push.

• Node.js 24 or later (the database uses the built-in node:sqlite)

• npm

Evidence import accepts each platform's own absolute-path shape: drive-letter paths on Windows, /-rooted paths on Linux and macOS. The rules genuinely differ — Windows also refuses UNC paths, alternate data streams and reserved device names, while the POSIX rules refuse embedded NUL bytes and the ambiguous // root — because the dangerous shapes differ, not because one platform is trusted more.

The credential vault differs too, and the differences are worth knowing before you rely on it. All three give the same practical guarantee — a data home copied to another machine or another account cannot be opened — but they are not equally strong:

None of them defends against software running as you, which SECURITY.md has always listed as out of scope. The ranking matters only if a local attacker is in your threat model; if so, prefer macOS or Windows, or do not store LinkedIn credentials at all — everything else works without them.

The interactive setup assistant is Windows-only, because it is PowerShell. On Linux and macOS you configure your MCP client by hand, which is one JSON block — see MCP server setup. npm run setup:mcp prints exactly that block, with the right data home for your platform, rather than failing.

The optional LinkedIn read lane has a second, separate limit: LinkedIn issues Member Data Portability tokens only to members located in the European Economic Area or Switzerland. Everything that does not touch LinkedIn works regardless.

Quick start

From the repository root:

npm run setup:mcp

On Windows this runs the interactive assistant described below. On Linux and macOS the assistant does not apply — it is PowerShell and writes Windows client paths — so npm run setup:mcp instead prints the one JSON block you add to your MCP client by hand, with the right data home for your platform, and the rest of this section (the PowerShell commands) is Windows-only. Per-client examples are in MCP server setup; the short version is Use the MCP without the dashboard below, which is identical on every platform.

See what it would do first (Windows):

powershell -NoProfile -ExecutionPolicy Bypass -File .\setup-mcp.ps1 -All -NonInteractive -DryRun

Windows refuses to run an unsigned .ps1 under its default Restricted execution policy, so a bare .\setup-mcp.ps1 fails before it does anything. -ExecutionPolicy Bypass applies to that one invocation and changes nothing on the machine — which is also exactly what npm run setup:mcp does. Read the script first if you would rather not take that on trust; -DryRun prints every file it would touch without opening any of them for writing.

The assistant edits configuration files that belong to other applications, so it is worth knowing which before you let it run. Depending on the clients you select it can write to ~/.codex/config.toml, ~/.claude.json, %APPDATA%\Claude\claude_desktop_config.json, %APPDATA%\Code\User\mcp.json, ~/.copilot/mcp-config.json, ~/.cursor/mcp.json, and ~/.gemini/config/mcp_config.json. Unless you pass -NoPersistUserEnvironment it also saves LINKEDIN_MCP_HOME as a user-scope environment variable.

Every file it touches is backed up with a timestamped copy first, only the linkedin entry is replaced, a file that is not strict JSON is refused rather than rewritten, and a failure restores the original.

The interactive assistant checks Node.js, installs dependencies when needed, builds the MCP server, asks which AI clients to configure, and points every selection at one shared data home. It supports Codex, Claude Code, Claude Desktop, VS Code/Copilot Chat, GitHub Copilot CLI, Cursor, and Google Antigravity. Existing JSON configurations are merged and backed up; only the linkedin MCP entry is replaced.

Restart the configured clients, then choose either or both surfaces:

# MCP server: normally started automatically by your AI client
npm run mcp:start

# Optional human review dashboard
npm run dashboard

mcp:start speaks JSON-RPC over stdin/stdout and therefore appears to wait when run in an ordinary terminal. That is expected. Configure an MCP client to launch it instead; see MCP server setup.

The dashboard prints a single-use URL for http://127.0.0.1:4780. See dashboard usage.

For repeatable or unattended setup:

powershell -NoProfile -ExecutionPolicy Bypass -File .\setup-mcp.ps1 -Clients Codex,Cursor,VSCode -NonInteractive
powershell -NoProfile -ExecutionPolicy Bypass -File .\setup-mcp.ps1 -All -NonInteractive

Use -DataHome "C:\absolute\path" to choose a different shared home. The assistant saves that absolute path as the current user's LINKEDIN_MCP_HOME; open a new terminal before starting the dashboard so it inherits a newly saved custom value. Pass -NoPersistUserEnvironment if you only want the selected client entries changed. The assistant never asks for or writes LinkedIn credentials.

Shared state between MCP and dashboard

The dashboard and every configured MCP process open the same local application home. You can work in the dashboard, close it, continue through an AI agent, and return later without importing or reconciling anything manually.

All paths below are under the data home (see Data location).

SQLite WAL mode and bounded write retries allow the dashboard and MCP clients to run at the same time. The dashboard refreshes the current screen when it regains focus and periodically while visible, so agent-side changes appear without restarting it.

This is local synchronization on one user account, not cloud or multi-machine synchronization. Secrets remain usable by both processes but are never copied into AI-client configuration, returned to a model, exported, logged, or included in backups.

Use the MCP without the dashboard

The dashboard and MCP server are separate processes. You do not need to start the dashboard before connecting Codex, Claude, Copilot, Cursor, Antigravity, VS Code, or another stdio MCP host.

After building, configure the client to launch the compiled entrypoint with an absolute path (backslashes on Windows, / on Linux and macOS):

node <absolute-path-to-repo>/linkedin-mcp-server/dist/index.js

To add and import the first evidence source from a human-operated terminal — the path is an example, use your own absolute path in the shape your platform accepts:

npm run evidence:add -- "C:\path\to\cv.pdf" document personal_doc "Current CV"
# Linux / macOS:  npm run evidence:add -- "/home/you/cv.pdf" document personal_doc "Current CV"

That command explicitly registers, enables, and imports the source without opening the dashboard. Source kinds are repo, document, folder, linkedin_export, and manual; trust levels are personal_doc, own_repo, and local_clone_reference.

You can then ask the connected agent to:

Use the LinkedIn MCP capability-status tool, then list my evidence sources and candidate claims.

The MCP drives the normal workflow. The dashboard includes purpose-built review screens plus System → All MCP tools, which exposes the exact same validated tool registry—there is no dashboard-only copy of the business logic. Secret entry is the only operation intentionally unavailable through chat. Other consequential operations require an explicit confirmation bound to the action:

Run npm run control with no arguments for an interactive menu. The CLI is also the dashboard-free secret-entry surface; access tokens are masked and never enter MCP payloads.

Shared feature controls

Nine feature groups are stored in the shared SQLite database and enforced by both MCP handlers and dashboard routes: evidence, profile, content, publication_workflow, analytics, linkedin_sync, maintenance, configuration, and live_publishing. The first eight default to enabled. Only live_publishing defaults to disabled.

List descriptions and current values with linkedin_feature_control, System → Features, or:

npm run control -- feature list
npm run control -- feature disable analytics --confirm
npm run control -- feature enable analytics --confirm

Feature policy is separate from LinkedIn credential/API readiness. Enabling live_publishing therefore still requires a verified write lane, and every real post still requires a granted revision-bound approval plus the exact publish command.

Evidence workflow and decisions

The intended flow is MCP-first:

1. Register an evidence path with MCP, then explicitly confirm ENABLE <source_id> through the agent, dashboard, or control CLI.

2. Let the agent import it, verify stored-byte integrity, inspect the extracted artifacts, and propose narrow claims with citations.

3. Review the exact statements. Non-conflicting claims become verified only after explicit human confirmation.

4. Escalate conflicts, ambiguous wording, and overstatements for human review. Resolve them through MCP conversation or the dashboard; both call the same claim and conflict services.

Claim statements are immutable history. “Modify” creates corrected wording as a new claim, then rejects or merges the old claim. This keeps previous decisions auditable instead of silently rewriting evidence.

Data location

The default home is each platform's own convention:

Set LINKEDIN_MCP_HOME to an absolute directory to use a different home or an isolated test corpus; it overrides the default on every platform. Relative paths are rejected because different client working directories could otherwise create separate databases — and on Windows a drive-relative path like \linkedin-data is rejected for the same reason, since it resolves against whichever drive a process is on. The setup assistant configures the same absolute value everywhere.

Do not place the live home in OneDrive, Dropbox, Google Drive, iCloud Drive, or another synchronization folder. SQLite uses a live WAL database, which should not be copied while open. Use the built-in backup command instead.

Repository map

Safety model

• Only verified claims can back public profile text or drafts.

• Imported content is always treated as untrusted data, never as instructions.

• MCP can grant, reject, or revise a publication request only after the user explicitly confirms the exact approval command; grants are bound to the revision hash.

• Approval is bound to one exact draft revision and consumed before publishing.

• An uncertain network outcome becomes ambiguous; it is never retried automatically.

• The audit log is hash-chained; a broken chain blocks approvals and publication.

• Imports copy content into the artifact store and never modify the originals.

• Secrets are excluded from MCP payloads, logs, exports, and backups.

Development and verification

npm ci
npm run typecheck
npm run build
npm test
npm run inspect:list
npm run test:visual

Build before test. The protocol-cleanliness suite drives the compiled stdio server, so npm test needs linkedin-mcp-server/dist/index.js to exist. Running the steps in the order above is enough; there is no separate setup.

inspect:list starts the compiled stdio server through MCP Inspector and requests its tool catalog. Visual tests require Playwright browser installation.

For optional LinkedIn developer-app configuration, see docs/linkedin-app-setup.md.

Documentation

License

MIT — see LICENSE. Third-party dependency licenses are listed in THIRD-PARTY-NOTICES.md; trademark and affiliation wording lives in NOTICE.