linkedin-mcp

An MCP (Model Context Protocol) server that lets AI agents publish to LinkedIn as the authenticated member — text posts, link shares, single/multi-image posts, reshares, comments, and reactions — with built-in safety rails for autonomous operation: daily budget limits, engagement deduplication, compact TOON-encoded responses, and self-describing errors with typo suggestions.

Authentication is OAuth 2.0 (3-legged) with a cluster-hosted callback protected by HTTP Basic Auth, so you never have to copy tokens onto a server by hand. Tokens, budgets, and dedup state live in a single JSON file you can back with a Kubernetes PVC.

Works with Claude Code, Claude Desktop, OpenAI Codex, Cursor, Windsurf, Cline, and any other MCP-compatible client — run it locally or via Docker.

Scope (Phase 1). LinkedIn's public API only allows member write actions plus reading your own profile. There is no public API to read the feed, search posts, list followers/connections, or follow people. This MCP is therefore publish-and-engage oriented. See spec.md for the full design and rationale.

---

What Can It Do?

Category	Tools	What You Can Say
Identity	get_me	"Who am I posting as?"
Publish	create_post, create_image_post, create_multi_image_post, reshare_post	"Post 'hello world' on LinkedIn" / "Share this image with a caption"
Media	upload_media	"Upload this image and post it"
Engage	comment_on_post, react_to_post	"Comment 'congrats' on this post" / "Like this post"
Lifecycle	delete_post	"Delete that post"

Post-targeting tools accept either a LinkedIn URN (urn:li:share:... / urn:li:ugcPost:... / urn:li:activity:...) or a post URL interchangeably.

---

Safety Features

Daily budget limits

Hard per-action limits per day. The server refuses when exhausted — even if the LLM ignores every instruction.

LI_MCP_MAX_POSTS=5       # Max posts/reshares per day (default)
LI_MCP_MAX_COMMENTS=10   # Max comments per day
LI_MCP_MAX_REACTIONS=30  # Max reactions per day
LI_MCP_MAX_DELETES=3     # Max post deletions per day

Set to 0 to disable an action entirely. Set to -1 for unlimited.

Budget counters in every response

Every response includes the remaining budget, so the LLM sees its limits proactively:

li_budget: "1/5 posts used, 0/10 comments used, 2/30 reactions used, 0/3 deletes used | last action: 3m ago"

Engagement deduplication (default on)

Never comment on or react to the same post twice. Set LI_MCP_DEDUP=false to disable.

TOON + compact responses (default on)

Responses use TOON and drop verbose fields to save tokens. Set LI_MCP_TOON=false for JSON, LI_MCP_COMPACT=false to keep full shapes.

Self-describing errors

Tools validate parameters and return actionable hints with fuzzy-matched suggestions for typos, so the LLM learns from mistakes instead of getting opaque errors.

Text formatting (automatic)

You pass post text as plain text — the server handles LinkedIn's quirks for you:

• LinkedIn parses commentary as "Little Text", where \ | { } @ [ ] ( ) < > # * _ ~ are reserved. An unescaped one (notably () silently truncates the post. The server escapes them automatically.
• #hashtags are preserved as clickable hashtags.
• Images are only attached once LinkedIn finishes processing them, so posts never render as "This post cannot be displayed".

---

Setup

1. Clone, install, build

git clone https://github.com/2060-io/linkedin-mcp.git
cd linkedin-mcp
npm install
npm run build

2. Create a LinkedIn app

1. Go to the LinkedIn Developer Portal and create an app (it must be linked to a Company Page).
2. On the Products tab, request Sign In with LinkedIn using OpenID Connect and Share on LinkedIn. This grants the openid, profile, email, and w_member_social scopes.
3. On the Auth tab, copy the Client ID and Client Secret, and add your Redirect URL (see below).

3. Configure credentials

cp .env.example .env

Fill in LINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRET, and LINKEDIN_REDIRECT_URI (must EXACTLY match a Redirect URL on the app). See .env.example for every option.

---

Authorize (get a member token)

OAuth tokens are minted once, then refreshed automatically until the refresh token expires (~1 year), at which point you re-authorize.

Option A — Local dev CLI

# LINKEDIN_REDIRECT_URI=http://localhost:8000/oauth/callback
npm run auth

Open the printed URL, approve, and the tokens are written to the local state file.

Option B — Cluster-hosted callback (recommended for k8s)

With MCP_TRANSPORT=http and LI_MCP_ADMIN_USER / LI_MCP_ADMIN_PASSWORD set, the server exposes Basic-Auth-protected OAuth routes:

GET /oauth/start     # redirects to LinkedIn consent
GET /oauth/callback  # LinkedIn returns here; tokens persisted to state file
GET /oauth/status    # shows whether a valid token is stored

Visit https://<public-host>/oauth/start, authenticate with Basic Auth, approve on LinkedIn, and the member tokens land on the PVC. See charts/README.md.

---

Run

# stdio (for local MCP clients)
MCP_TRANSPORT=stdio npm start

# http (for cluster / remote)
MCP_TRANSPORT=http MCP_PORT=8000 npm start

HTTP endpoints: /mcp (StreamableHTTP), /healthz, and /oauth/*.

Connect a client (stdio example)

{
  "mcpServers": {
    "linkedin": {
      "command": "node",
      "args": ["/absolute/path/to/linkedin-mcp/dist/index.js"],
      "env": { "MCP_TRANSPORT": "stdio" }
    }
  }
}

---

Deploy to Kubernetes

A Helm chart is provided in charts/. It provisions a PVC for token/budget state, runs a single replica with the Recreate strategy, and wires LinkedIn + Basic Auth credentials through a Secret. See charts/README.md for install and authorization steps.

---

State persistence

All durable state — OAuth tokens (the source of truth), daily budget counters, and engagement dedup — lives in one JSON file (LI_MCP_STATE_FILE, default {cwd}/linkedin-mcp-state.json). On Kubernetes, back it with a PVC so tokens survive restarts; otherwise a restart forces re-authorization and resets budgets.

---

Development

npm run build   # tsc
npm test        # vitest
npm run dev     # build + start

---

Credits

TOON encoder vendored from @toon-format/toon (MIT). Architecture mirrors the sibling x-autonomous-mcp.

License

MIT