linkedin-safe-mcp

An MCP server that gives AI agents (Claude Code, Codex, Claude Desktop, Cursor, …) LinkedIn superpowers — without putting your LinkedIn account at risk:

• Post to LinkedIn — text, links, and images via LinkedIn's official API (OAuth, ToS-compliant), plus comments and likes.

• Search jobs — keyword/location/remote/experience/date filters via LinkedIn's public guest endpoints. No login, no cookies: your account is never involved.

• Run a job hunt — a local SQLite application tracker (interested → applied → interviewing → offer) with notes and per-job posting snapshots, so an agent can manage your pipeline and write tailored cover letters even after a posting is taken down.

Why this design?

LinkedIn offers no official job-search API, and the unofficial routes (Voyager internal API with your li_at session cookie, headless browsers on your logged-in session) violate LinkedIn's User Agreement §8.2 and routinely get accounts restricted. This server deliberately splits the difference:

Requirements

• Python 3.11+ and uv

• For posting only: a free self-serve LinkedIn developer app (5-minute setup below). Job search and the tracker work with zero setup.

Install & connect to your agent

Clone/copy this directory, then register it with your MCP client. <REPO> below is the absolute path to this project.

Claude Code

claude mcp add linkedin \
  --env LINKEDIN_CLIENT_ID=your_client_id \
  --env LINKEDIN_CLIENT_SECRET=your_client_secret \
  -- uv run --directory <REPO> linkedin-safe-mcp

Or in a project's .mcp.json:

{
  "mcpServers": {
    "linkedin": {
      "command": "uv",
      "args": ["run", "--directory", "<REPO>", "linkedin-safe-mcp"],
      "env": {
        "LINKEDIN_CLIENT_ID": "your_client_id",
        "LINKEDIN_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Codex (~/.codex/config.toml)

[mcp_servers.linkedin]
command = "uv"
args = ["run", "--directory", "<REPO>", "linkedin-safe-mcp"]
env = { LINKEDIN_CLIENT_ID = "your_client_id", LINKEDIN_CLIENT_SECRET = "your_client_secret" }

Claude Desktop (claude_desktop_config.json) — same JSON shape as .mcp.json above.

The LINKEDIN_CLIENT_* variables are only needed for posting; omit them if you only want job search + tracking.

Enabling posting (one-time LinkedIn app setup)

1. Go to https://www.linkedin.com/developers/apps → Create app (requires associating any LinkedIn Page; you can create a trivial one).

2. On the app's Products tab, add Share on LinkedIn and Sign In with LinkedIn using OpenID Connect.

3. On the Auth tab, add the redirect URL http://127.0.0.1:8765/callback (it must be the IP literal, not localhost — see Security below).

4. Copy the Client ID and Client Secret into the env vars shown above.

5. Authenticate once — either way works:

   • In a terminal: uv run --directory <REPO> linkedin-safe-mcp auth

   • Or just ask your agent to post something; it will call the login tool and hand you the authorization URL.

Tokens are stored in ~/.linkedin-mcp/tokens.json, created mode 0600 inside a 0700 directory, and last ~60 days; LinkedIn doesn't issue refresh tokens to self-serve apps, so you re-run the login when it expires (auth_status tells the agent exactly when that is). LinkedIn doesn't issue refresh tokens to self-serve apps, so you re-run the login when it expires (auth_status tells the agent exactly when that is).

Tools

Things agents can do with this: "find remote staff-engineer roles posted this week, save the promising ones, draft tailored cover letters from the saved descriptions, mark the ones I applied to, and post a summary of my open-source work."

Configuration

Behavior notes & limits

• Posting: LinkedIn caps member posting at 150 requests/day and rejects exact duplicates of recent posts (422). Reserved characters in post text are escaped automatically for the versioned API so parentheses don't cause errors; hashtags are preserved.

• Job search: guest endpoints are rate-limited per IP (HTTP 429). The server caches results (10 min searches / 6 h job details), retries with backoff, and paces multi-page fetches; on a persistent 429 it returns a clear "wait a minute" error to the agent. Keep limit modest.

• Scraping posture: guest job search reads the same public pages a logged-out visitor sees, at human-ish rates, with caching to minimize load. Still, LinkedIn could change or gate these endpoints at any time — the parsers are pinned by fixture tests so breakage is detected loudly, and the tool errors stay agent-actionable.

Security

The threat model assumes the agent driving this server is not trusted: it reads job descriptions scraped from LinkedIn, so a hostile posting is a prompt-injection channel straight into every tool argument. The boundaries that follow from that:

• Image attachments are not a file-read primitive. create_post(image_path=…) accepts only real PNG/JPEG/GIF files — verified by magic bytes and the format's mandatory trailer, so neither renaming a secret nor appending one after a valid header gets through — at most 10 MB, never via a symlink, hardlink, pipe or device. Without this, "attach ~/.ssh/id_rsa" was a valid call that published the key. Residual limit: an attacker who can already both read a secret and write files could encode it inside a structurally valid image; no format check can prevent that. Set LINKEDIN_MCP_IMAGE_DIR to confine uploads to one folder if that matters to you.

• The OAuth callback validates state before anything else. The listener on 127.0.0.1 is reachable by any local process and by any web page the user has open, so an unauthenticated request must not be able to abort a pending login (which would also free the port for an authorization-code interceptor). Error text is HTML-escaped at the sink.

• The redirect URL is 127.0.0.1, never localhost. Browsers may resolve the name to ::1, which a different local account can bind. RFC 8252 §8.3.

• Secrets are 0600 from creation. Tokens, state.json and the tracker DB are created private rather than chmod-ed afterwards, closing the window where a local watcher could read a fresh access token; ~/.linkedin-mcp is 0700.

• Upload targets are pinned. The Bearer token is only ever PUT to an HTTPS linkedin.com/licdn.com host, whatever URL the API response asks for.

These are covered by regression tests (tests/test_client_security.py, the security sections of tests/test_oauth.py and tests/test_tracker.py) — each one is a working exfiltration or hijack attempt that must fail closed.

Found something? Open an issue, or email the address on the GitHub profile for anything sensitive.

Development

uv sync            # install deps (Python ≥3.11)
uv run pytest      # 102 tests: parsers vs live fixtures, payloads, OAuth, tracker,
                   # security regressions, plus an end-to-end stdio smoke test
                   # that spawns the real server
uv run ruff check src tests && uv run ruff format --check src tests

Layout: src/linkedin_mcp/ — server.py (tool surface) · api/ (official REST: posts, social actions, uploads, dual rest/ugc backend) · auth/ (OAuth + token store) · jobs/ (guest client, HTML parsers, filter mappings) · tracker/ (SQLite store) · cli.py (serve | auth | status | logout).

Roadmap

• Publish to PyPI (uvx linkedin-safe-mcp one-liner)

• Reaction types beyond like; multi-image posts; poll posts

• Optional third-party job-data providers behind the same tool schema

• streamable-http transport for remote/hosted use

• (Considered, opt-in only, off by default) a cookie-based Voyager provider for personalized features — with loud warnings, since it violates LinkedIn's ToS

License

MIT