linkedin-mcp-zero 0.4.8

A high-performance, public-first Model Context Protocol (MCP) server for real-time LinkedIn talent intelligence, hybrid semantic RAG matching, ghost-job viability scoring, dynamic skill graphs, and privacy-first resume analysis.

Zero Login Required (33 Default Public/Local Tools) · 45 Catalog Tools · FastMCP 2.0 Native · Dual Stdio/HTTP Transports

⚡ Quickstart • 🎬 Live Demo • 🛠️ 45 Tools • 🏗️ Architecture • 📊 Benchmarks • 🚀 Deployment • 🛡️ Security • ❓ FAQ

🌟 What Sets LinkedIn MCP Zero Apart

⚡ Quickstart & One-Command Setup

Option A: Automatic Client Configuration (Recommended)

LinkedIn MCP Zero can automatically configure your favorite AI development environment with a single command:

# 🖥️ Anthropic Claude Desktop (macOS / Windows / Linux)
uvx linkedin-mcp-zero --install-client claude-desktop

# ⚡ Cursor IDE (Project or Global)
uvx linkedin-mcp-zero --install-client cursor

# 💻 Claude Code CLI
uvx linkedin-mcp-zero --install-client claude-code

# 📝 VS Code (Cline / Roo Code / MCP Extension)
uvx linkedin-mcp-zero --install-client vscode

# 🔮 Google Antigravity IDE & Agent Framework
uvx linkedin-mcp-zero --install-client antigravity

Option B: Verify System Health (--doctor)

Run the automated diagnostic suite to inspect your Python runtime, SQLite FTS5 support, and live network reachability:

uvx linkedin-mcp-zero --doctor

Option C: Supported AI Tool Integrations & Configurations

Choose your preferred AI client environment below for copy-pasteable JSON configurations and instant setup:

1. Anthropic Claude Desktop

Configuration File Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "linkedin-zero": {
      "command": "uvx",
      "args": [
        "linkedin-mcp-zero"
      ]
    }
  }
}

2. Cursor IDE

Configuration File Location:

• Workspace: .cursor/mcp.json
• Global: ~/.cursor/mcp.json

{
  "mcpServers": {
    "linkedin-zero": {
      "command": "uvx",
      "args": [
        "linkedin-mcp-zero"
      ]
    }
  }
}

3. Visual Studio Code (Cline / Roo Code / Continue)

Configuration File Location:

• macOS: ~/Library/Application Support/Code/User/mcp.json
• Linux: ~/.config/Code/User/mcp.json
• Windows: %APPDATA%\Code\User\mcp.json

{
  "servers": {
    "linkedin-zero": {
      "command": "uvx",
      "args": [
        "linkedin-mcp-zero"
      ]
    }
  }
}

4. Claude Code CLI

One-line terminal command:

claude mcp add linkedin-zero -- uvx linkedin-mcp-zero

5. Google Antigravity IDE & Agent Framework

Configuration File Location:

• Workspace: .agents/mcp_config.json
• Global: ~/.gemini/antigravity-ide/mcp_config.json or ~/.gemini/config/mcp_config.json

{
  "mcpServers": {
    "linkedin-zero": {
      "command": "uvx",
      "args": [
        "linkedin-mcp-zero"
      ]
    }
  }
}

6. Cloud Hosted / Remote Streamable-HTTP

For remote web apps, distributed teams, or hosted agents connecting over HTTP SSE:

{
  "mcpServers": {
    "linkedin-zero-remote": {
      "url": "https://linkedin-mcp-zero.onrender.com/mcp",
      "headers": {
        "x-api-key": "your-secure-api-token"
      }
    }
  }
}

🎬 Animated Live Execution Demo

Here is a visual recording of LinkedIn MCP Zero executing a live zero-login query, performing FTS5 Porter BM25 indexing, calculating ghost-job viability, and dynamically updating the SQLite skill co-occurrence graph in real time:

=== REAL-TIME LINKEDIN INSPECTION ===
Query: "Staff AI Engineer" in "San Francisco, CA"

1. Live Public Network Retrieval:
   [1] ID: 4475151136 | Staff Systems Engineer, Inference @ Anthropic (San Francisco, CA)
   [2] ID: 4483675233 | Research Engineer, Model Optimization @ OpenAI (San Francisco, CA)
   [3] ID: 4301398088 | Principal AI Platform Engineer @ Databricks (San Francisco, CA)

2. Live Job Detail & Dynamic Skill Extraction:
   Title:    Staff Systems Engineer, Inference Infrastructure
   Company:  Anthropic
   Skills:   ['Python', 'PyTorch', 'CUDA', 'Distributed Systems', 'Triton']
   Desc:     "Anthropic is building reliable, interpretable, and steerable AI systems..."

3. SQLite FTS5 BM25 Indexing:
   BM25 Search for "PyTorch": Found Anthropic Staff Systems Engineer (Rank: -0.842)

4. Real-Time Viability & Saturation Analysis:
   Status:          ACTIVE_HIGH_PRIORITY
   Viability Score: 0.98 / 1.0 (0 reposts, posted 4h ago, 28 applicants)

5. Dynamically Learned Graph Connections:
   "PyTorch" dynamically linked to:
      -> cuda (weight: 5.8)
      -> distributed systems (weight: 3.2)
      -> triton (weight: 1.0)
      -> llm serving (weight: 2.1)

🛠️ Complete Interactive Tool Matrix (45 Tools)

LinkedIn MCP Zero provides 45 synchronized production tools organized into distinct risk tiers.

🛡️ Zero-Login Guarantee: 33 core tools require zero credentials, zero sessions, and zero browser automation. Your personal LinkedIn account is never touched and remains 100% protected.

🏗️ System Flow & Hybrid RAG Architecture

1. High-Level System Flow

flowchart TD
    classDef client fill:#1e1e38,stroke:#8B5CF6,stroke-width:2px,color:#fff;
    classDef server fill:#0f172a,stroke:#0A66C2,stroke-width:2px,color:#fff;
    classDef engine fill:#064e3b,stroke:#10B981,stroke-width:2px,color:#fff;
    classDef rag fill:#312e81,stroke:#6366F1,stroke-width:2px,color:#fff;
    classDef ext fill:#18181b,stroke:#71717a,stroke-width:1.5px,color:#fff;

    subgraph ClientLayer["🤖 AI Clients & Orchestrators"]
        C1["Claude Desktop"]:::client
        C2["Cursor IDE"]:::client
        C3["Claude Code CLI"]:::client
        C4["Remote Agent via Streamable-HTTP"]:::client
    end

    subgraph CoreServer["⚡ LinkedIn MCP Zero (FastMCP 2.0 Engine)"]
        direction TB
        
        MW["Security & Rate Limiting Middleware<br/>(RFC 6585 · Single-Flight Coalescer · OAuth 2.1)"]:::server
        Router{"45-Tool Router"}:::server

        subgraph ScrapeEngine["Live Guest Scraping Engine"]
            CF["curl_cffi Chrome 124 TLS Impersonator"]:::engine
            HP["JSON-LD & DOM Extractors"]:::engine
            JIT["Cryptographic Jitter (secrets)"]:::engine
        end

        subgraph RAGEngine["Hybrid Retrieval & Knowledge Engine"]
            FTS["SQLite FTS5 Full-Text Index<br/>(Unicode61 Porter Stemming)"]:::rag
            VEC["Dense Semantic Vector Store<br/>(Cosine Similarity)"]:::rag
            RRF["Reciprocal Rank Fusion (RRF)<br/>Score = 1 / (60 + Rank_BM25) + 1 / (60 + Rank_Vec)"]:::rag
            DSG["Dynamic In-Process Skill Graph<br/>(Real-Time Edge Weight Co-occurrence)"]:::rag
        end

        subgraph Intelligence["Decision & Viability Intelligence"]
            GHOST["Ghost Job & Saturation Detector<br/>(analyze_job_viability)"]:::server
            RESUME["Privacy-First Resume Parser<br/>(PDF / DOCX / Text)"]:::server
            LLM_BRIDGE["LLM Sampling Bridge<br/>(Client-Side or Provider API)"]:::server
        end
    end

    subgraph ExternalWeb["🌍 Production Web"]
        LI["LinkedIn Public Gateway<br/>(Guest Search Endpoints)"]:::ext
        MB["Multi-Board Engines<br/>(Indeed, Glassdoor, RemoteOK)"]:::ext
    end

    ClientLayer <==>|Stdio / Streamable-HTTP| MW
    MW --> Router
    Router --> ScrapeEngine
    Router --> RAGEngine
    Router --> Intelligence

    ScrapeEngine <==>|Direct HTTPS TLS| LI
    ScrapeEngine <==>|Direct HTTPS| MB

    HP --> FTS
    HP --> DSG
    RESUME --> DSG
    FTS & VEC --> RRF

2. End-to-End Execution Sequence

sequenceDiagram
    autonumber
    actor User as AI Client (Claude / Cursor / Agent)
    participant MW as Security Middleware & Coalescer
    participant FastMCP as FastMCP 2.0 Router
    participant Engine as Live Scraping Engine (curl_cffi)
    participant Web as LinkedIn Public Gateway
    participant SQLite as SQLite FTS5 & Skill Graph
    participant RRF as Hybrid RRF Ranker

    User->>MW: Call tool: search_jobs("Staff AI Engineer", "SF")
    MW->>FastMCP: Deduplicated Request Passed (Single-Flight Protected)
    FastMCP->>Engine: Dispatch Scraping Task
    Engine->>Web: TLS Chrome 124 Impersonated GET Request
    Web-->>Engine: 200 OK (Live HTML & JSON-LD Postings)
    Engine->>SQLite: Index Postings into FTS5 & Learn Skill Co-occurrences
    FastMCP->>RRF: Query FTS5 BM25 + Vector Similarity
    RRF-->>FastMCP: Reciprocal Rank Fused Scores (k=60)
    FastMCP-->>User: Structured Clean JSON Payload (<600 tokens)

3. Concrete Architectural Implementation Layers

LinkedIn MCP Zero is structured into 5 decoupled, production-hardened subsystems:

Layer 1: Unified Transport & Gateway

• Implementation: src/linkedin_mcp_zero/server/app.py & src/linkedin_mcp_zero/server/middleware.py
• FastMCP 2.0 Native: Supports both local process IPC (stdio) for desktop AI clients and asynchronous network daemon (streamable-http) for cloud containers.
• Security Middleware: Sliding-window rate limiting emitting RFC 6585 Retry-After: 60 headers, token verification, and OAuth 2.1 metadata endpoint.

Layer 2: Zero-Login Scraping & Impersonation Engine

• Implementation: src/linkedin_mcp_zero/engines/public_api.py & src/linkedin_mcp_zero/engines/multi_board.py
• Browser-Grade TLS: Uses curl_cffi targeting public LinkedIn guest endpoints (/jobs-guest/jobs/api/seeMoreJobPostings/search) with Chrome 124 JA3/JA4 TLS fingerprinting.
• Single-Flight Coalescing: Duplicate parallel requests for identical queries share the same in-flight task to eliminate thundering herds and IP rate limits.
• Anti-Fingerprinting: Cryptographic randomness via Python secrets for headers, User-Agent rotations, and network jitter.

Layer 3: Hybrid RAG & Reciprocal Rank Fusion (RRF)

• Implementation: src/linkedin_mcp_zero/storage/db.py & src/linkedin_mcp_zero/storage/vector_db.py
• SQLite FTS5 Full-Text: Embedded full-text virtual table with Unicode61 Porter tokenization delivering instant BM25 lexical rank.
• Dense Cosine Vectors: Lightweight in-process vector store computing semantic embedding similarity.
• RRF Score Fusion: Fuses lexical BM25 and dense semantic scores using Reciprocal Rank Fusion ($k=60$): $$\text{Score}{\text{RRF}}(d) = \sum{m \in {\text{BM25}, \text{Vector}}} \frac{1}{60 + \text{Rank}_m(d)}$$

Layer 4: Real-Time Dynamic Skill Graph

• Implementation: src/linkedin_mcp_zero/config/skills.py & src/linkedin_mcp_zero/storage/db.py
• Continuous In-Process Learning: 200+ canonical technical skill nodes. When live postings or candidate resumes are analyzed, co-occurring technologies dynamically update edge weights in SQLite: $$\text{Weight}{A \leftrightarrow B} \leftarrow \text{Weight}{A \leftrightarrow B} + 1.0$$
• Allows instant query expansion and technology ecosystem exploration via expand_skill_cluster.

Layer 5: Decision Intelligence & Viability Scoring

• Implementation: src/linkedin_mcp_zero/engines/matching.py & src/linkedin_mcp_zero/engines/resume.py
• Ghost-Job Viability Engine (analyze_job_viability): Algorithmic detection evaluating posting age, applicant pool volume, repost frequencies, and hiring velocity.
• Local In-Memory Resume Parsing: Extracts structured skills, experience, and education from PDF, DOCX, and TXT with zero cloud data transmission.
• Model-Agnostic LLM Bridge (src/linkedin_mcp_zero/utils/llm.py): Supports client-side sampling (Claude, Cursor, Gemini) with optional direct OpenAI and Anthropic provider execution.

📊 Feature Comparison Matrix

🚀 Production Deployment & Cloud Hosting

LinkedIn MCP Zero can be executed locally as a stdio child process or hosted online as a high-performance cloud service via Streamable HTTP / SSE mode.

HTTP / Cloud Endpoints

• Service Status & Discovery: GET / (Public JSON status and tool count)
• Health & Diagnostic Probe: GET /health (Liveness & readiness probe for cloud balancers)
• MCP 2.0 Streaming SSE: GET /sse or POST /sse (Streamable MCP endpoint for remote AI agents)
• OAuth 2.1 Discovery: GET /.well-known/oauth-protected-resource (RFC 9728 metadata)

Cloud Provider Quickstart

1. Render (1-Click or Blueprint)

Deploy automatically using render.yaml:

• Click Deploy to Render above or connect your GitHub repository in the Render Dashboard.
• Render automatically provisions the Docker container, configures the /health check, and sets an auto-generated LINKEDIN_MCP_API_KEY.

2. Railway (1-Command CLI)

Deploy using the Railway CLI and railway.json:

npm i -g @railway/cli
railway login
railway init
railway up

3. Fly.io (Global Edge Deployment)

Deploy across worldwide regions using fly.toml:

fly launch --no-deploy
fly secrets set LINKEDIN_MCP_API_KEY="your-secure-key"
fly deploy

4. Pre-built Docker Container (GitHub Container Registry)

Run the pre-built, hardened multi-arch image directly:

docker run -d -p 8000:8000 \
  -e LINKEDIN_MCP_API_KEY="your-secure-token" \
  -e RATE_LIMIT_PER_MINUTE=120 \
  --name linkedin-mcp-zero \
  ghcr.io/santhakumar-k-2004/linkedin-mcp-zero:latest

5. Kubernetes Cluster

Deploy to any Kubernetes cluster (GKE, EKS, AKS, or local Minikube/k3s):

kubectl apply -f deploy/k8s.yaml

🌐 Connecting Remote AI Clients to Hosted Server

Once hosted online (e.g. https://your-service.onrender.com), connect your favorite AI client using the remote SSE transport:

🖥️ Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "linkedin-remote": {
      "url": "https://your-service.onrender.com/sse",
      "headers": {
        "x-api-key": "your-secure-token"
      }
    }
  }
}

⚡ Cursor IDE (.cursor/mcp.json)

{
  "mcpServers": {
    "linkedin-remote": {
      "url": "https://your-service.onrender.com/sse",
      "headers": {
        "x-api-key": "your-secure-token"
      }
    }
  }
}

🔮 Google Antigravity IDE (.agents/mcp_config.json)

{
  "mcpServers": {
    "linkedin-remote": {
      "url": "https://your-service.onrender.com/sse",
      "headers": {
        "x-api-key": "your-secure-token"
      }
    }
  }
}

📝 VS Code

{
  "servers": {
    "linkedin-remote": {
      "url": "https://your-service.onrender.com/sse",
      "headers": {
        "x-api-key": "your-secure-token"
      }
    }
  }
}

🔍 Verification & Health Checking

Verify your remote deployment is live and healthy:

# Liveness probe
curl -f https://your-service.onrender.com/health

# Discovery endpoint
curl -H "x-api-key: your-secure-token" https://your-service.onrender.com/

🔒 Security & Privacy Model

LinkedIn MCP Zero is architected around strict defense-in-depth principles:

1. Zero-Login by Default: 33 of 45 tools require no authentication, no credentials, and no cookies. Your account cannot be banned or restricted because it is never used.
2. Privacy-First Local Resume Parsing: PDF, DOCX, and text resume extraction (analyze_resume, match_jobs_to_resume) runs completely in local memory on your device using native parsers. Candidate PII, resumes, and contacts are never sent to external analytics or telemetry services.
3. Transparent Client LLM Reasoning: Qualitative reasoning tools (tailor_resume, smart_match_jobs, generate_cover_letter, get_resume_insights_advanced) pass parsed candidate details strictly to your configured AI client (Claude, Cursor, Gemini, or local Ollama) as part of your prompt context. You retain 100% control over the prompt context.
4. Spreadsheet Formula Injection Neutralization: All CSV/XLSX export routines prefix any cell starting with =, +, -, @, or tab characters with ' to mitigate CVE-style CSV macro execution.
5. SSRF Domain Protection: Internal browser scrapers strictly enforce LinkedIn and recognized multi-board hostname validation to prevent unauthorized network pivot attempts.
6. Cryptographic Randomness: All jitter delays, user-agent rotations, and temporary identifiers use Python's cryptographically secure secrets module instead of predictable pseudo-random seeds.
7. Single-Flight Request Coalescing: Duplicate parallel requests for the same LinkedIn job or company URL are coalesced into a single flight, preventing thundering-herd rate limiting.
8. RFC 6585 Rate Limiting: Intelligent sliding-window rate limiters emit standard Retry-After: 60 headers and thread-safe circuit breakers when upstream rate limits are approached.

💻 Local Development & Testing

# Clone repository
git clone https://github.com/SanthaKumar-K-2004/linkedin-mcp-zero.git
cd linkedin-mcp-zero

# Install with development extras
uv sync --extra dev

# Run comprehensive test suite (125 unit tests)
uv run pytest tests/ -v

# Code quality and formatting checks
uv run ruff check .
uv run ruff format --check .

# Strict static type analysis
uv run mypy src/

# Automated security vulnerability scan
uv run bandit -r src/ -x tests -ll

# Build distributable wheel and source packages
uv build

❓ Frequently Asked Questions

📄 License & Community

Licensed under the Apache License, Version 2.0. See the LICENSE file for complete details.