Metadata-Version: 2.4
Name: mcp-server-linkedin-zero
Version: 0.1.1
Summary: Token-optimized, zero-risk LinkedIn jobs MCP server.
Author: Santhakumar K
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.28
Requires-Dist: lxml>=5.3
Requires-Dist: platformdirs>=4.3
Requires-Dist: pydantic-settings>=2.7
Requires-Dist: pydantic>=2.10
Requires-Dist: python-docx>=1.1
Requires-Dist: rich>=13.9
Requires-Dist: structlog>=24.4
Provides-Extra: browser
Requires-Dist: patchright>=1.49; extra == 'browser'
Requires-Dist: playwright>=1.49; extra == 'browser'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: multi
Requires-Dist: python-jobspy>=1.1.82; extra == 'multi'
Provides-Extra: pdf
Requires-Dist: pymupdf>=1.25; extra == 'pdf'
Description-Content-Type: text/markdown

<div align="center">

```text
██╗     ██╗███╗   ██╗██╗  ██╗███████╗██████╗ ██╗███╗   ██╗
██║     ██║████╗  ██║██║ ██╔╝██╔════╝██╔══██╗██║████╗  ██║
██║     ██║██╔██╗ ██║█████╔╝ █████╗  ██║  ██║██║██╔██╗ ██║
██║     ██║██║╚██╗██║██╔═██╗ ██╔══╝  ██║  ██║██║██║╚██╗██║
███████╗██║██║ ╚████║██║  ██╗███████╗██████╔╝██║██║ ╚████║
╚══════╝╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝╚═════╝ ╚═╝╚═╝  ╚═══╝
             MCP ZERO - public-first LinkedIn intelligence
```

# LinkedIn MCP Zero

**32 MCP tools for jobs, resumes, matching, alerts, exports, and optional read-only browser intelligence.**

No Docker required · Public-first · Low-RAM friendly · FastMCP · PyPI published

[![PyPI](https://img.shields.io/pypi/v/mcp-server-linkedin-zero?color=0A66C2)](https://pypi.org/project/mcp-server-linkedin-zero/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-stdio%20%7C%20http-purple)](https://modelcontextprotocol.io/)

</div>

## The Promise

LinkedIn MCP Zero gives AI agents useful LinkedIn intelligence while staying
honest about risk:

| Principle | What it means |
|---|---|
| Public-first | Job search/details use public LinkedIn guest endpoints. No account required. |
| Read-only | No automated posting, applying, connecting, or messaging. |
| Local by default | Resume parsing, alerts, matching, exports, and state live on your machine. |
| Lazy browser | Chrome/CDP tools load only when called, then auto-unload after idle time. |
| Low-spec friendly | The server detects RAM/disk and recommends `full`, `balanced`, or `lean`. |
| Easy install | Claude Code, Claude Desktop, Cursor, and custom MCP clients work with one command. |

## Install In 10 Seconds

Check your system:

```bash
uvx mcp-server-linkedin-zero --doctor
```

Run as an MCP server:

```bash
uvx mcp-server-linkedin-zero
```

Use the latest GitHub source instead of PyPI:

```bash
uvx --from git+https://github.com/SanthaKumar-K-2004/linkedin-mcp-zero mcp-server-linkedin-zero --doctor
```

## One-Line Agent Setup

Claude Code:

```bash
claude mcp add linkedin-zero -- uvx mcp-server-linkedin-zero
```

Claude Desktop:

```bash
uvx mcp-server-linkedin-zero --install-client claude-desktop
```

Cursor, run inside the project where you want `.cursor/mcp.json`:

```bash
uvx mcp-server-linkedin-zero --install-client cursor
```

Custom MCP clients:

```bash
uvx mcp-server-linkedin-zero
```

Streamable HTTP:

```bash
uvx mcp-server-linkedin-zero --transport streamable-http --host 127.0.0.1 --port 8000
```

GitHub-source agent setup:

```bash
claude mcp add linkedin-zero -- uvx --from git+https://github.com/SanthaKumar-K-2004/linkedin-mcp-zero mcp-server-linkedin-zero
```

## Safe Auto Config

The installer does not overwrite your whole MCP config. It:

- Finds the right config path for Claude Desktop or Cursor.
- Creates missing folders.
- Reads existing JSON.
- Preserves every other MCP server.
- Adds or updates only `linkedin-zero`.
- Creates a timestamped `.bak` backup before saving.
- Writes JSON atomically.

Manual config:

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

Print the config without editing files:

```bash
uvx mcp-server-linkedin-zero --print-config
```

## Platform Matrix

| Platform | Command |
|---|---|
| Claude Code | `claude mcp add linkedin-zero -- uvx mcp-server-linkedin-zero` |
| Claude Desktop | `uvx mcp-server-linkedin-zero --install-client claude-desktop` |
| Cursor | `uvx mcp-server-linkedin-zero --install-client cursor` |
| Custom stdio client | `uvx mcp-server-linkedin-zero` |
| HTTP client | `uvx mcp-server-linkedin-zero --transport streamable-http --port 8000` |
| Docker | Not required |
| Low-spec laptop | Supported, browser tools stay lazy |

## What `--doctor` Checks

```bash
uvx mcp-server-linkedin-zero --doctor
```

It detects:

- OS and Python version.
- Python executable.
- CPU count.
- Total and available RAM.
- Free disk.
- Local data directory.
- Chrome, Chromium, Brave, or Edge.
- CDP URL.
- Docker/display state.
- Optional packages: JobSpy, PyMuPDF, Playwright, Patchright.
- Recommended mode: `full`, `balanced`, or `lean`.

Example:

```json
{
  "python": "3.12.13",
  "cpu_count": 8,
  "ram_total_mb": 7135,
  "ram_available_mb": 2539,
  "chrome": "/usr/bin/google-chrome",
  "mode": "full",
  "notes": ["Browser tools need `uv sync --extra browser`."]
}
```

## Tool Inventory

| # | Tool | Engine | Risk | What it does |
|---|---|---|---|---|
| 1 | `search_jobs` | E1 | Zero | Search LinkedIn jobs |
| 2 | `search_jobs_multi` | E1 | Zero | Search LinkedIn, Indeed, Google, ZipRecruiter, Glassdoor |
| 3 | `get_job_details` | E1 | Zero | Full public job details |
| 4 | `get_company_jobs` | E1 | Zero | Public jobs at a company |
| 5 | `get_company_profile` | E1 | Zero | Company signals from public jobs |
| 6 | `search_companies` | E1 | Zero | Company search from job signals |
| 7 | `get_job_salary` | E1 | Zero | Salary extraction |
| 8 | `get_job_trends` | E1 | Zero | Role/location trend summary |
| 9 | `get_industry_insights` | E1 | Zero | Industry job insights |
| 10 | `search_jobs_advanced` | E1 | Zero | Search with filters |
| 11 | `analyze_resume` | RE | Zero | Parse TXT, MD, DOCX, optional PDF |
| 12 | `get_resume_insights` | RE | Zero | Skill gaps and suggestions |
| 13 | `match_jobs_to_resume` | ME | Zero | Rank jobs against resume |
| 14 | `compare_jobs` | ME | Zero | Compare 2-5 jobs |
| 15 | `export_jobs` | LO | Zero | CSV/JSON export |
| 16 | `save_job_alert` | ST | Zero | Save recurring search |
| 17 | `get_saved_alerts` | ST | Zero | List alerts |
| 18 | `check_saved_alerts` | E1+ST | Zero | Run alerts and find new matches |
| 19 | `get_my_profile` | E2 | Minimal | Read your profile through Chrome CDP |
| 20 | `get_person_profile` | E2 | Minimal | Read a public/person profile |
| 21 | `search_people` | E2 | Minimal | LinkedIn people search |
| 22 | `get_my_connections` | E2 | Minimal | Read connection list |
| 23 | `get_inbox` | E2 | Minimal | Read inbox list |
| 24 | `get_conversation` | E2 | Minimal | Read one thread |
| 25 | `get_feed` | E2 | Minimal | Read home feed |
| 26 | `get_notifications` | E2 | Minimal | Read notifications |
| 27 | `get_sidebar_profiles` | E2 | Minimal | Read sidebar suggestions |
| 28 | `get_company_employees` | E2 | Low | Read company people page |
| 29 | `check_session` | E2 | Minimal | Check Chrome/CDP readiness |
| 30 | `get_engine_status` | System | Zero | Runtime and engine status |
| 31 | `get_help` | System | Zero | Tool documentation |
| 32 | `get_profile_voyager` | E3 | Low | Gated off by default |

## Architecture

```text
Claude / Cursor / Custom Agent
        |
        | MCP stdio or Streamable HTTP
        v
┌──────────────────────────────────────────────────────────────┐
│ LinkedIn MCP Zero                                            │
│                                                              │
│  FastMCP tool layer  ->  32 compact tools                    │
│          |                                                   │
│          +-- E1 Public APIs      LinkedIn guest jobs         │
│          +-- Resume Engine       local TXT/MD/DOCX/PDF       │
│          +-- Matching Engine     local scoring               │
│          +-- Storage             SQLite + exports            │
│          +-- E2 Browser          real Chrome via CDP         │
│          +-- E3 Voyager          off by default              │
│                                                              │
│  Shared: cache, rate limit, config, autodetect, logging      │
└──────────────────────────────────────────────────────────────┘
```

## Hidden Gems Wired

| Hidden gem | Used for |
|---|---|
| LinkedIn Guest Jobs API | Zero-login public job search/details |
| JobSpy | Optional 5-board job search |
| JSON-LD Schema.org | Stable salary, skills, dates, job detail parsing |
| FastMCP | MCP server, schemas, stdio/HTTP transports |
| Chrome DevTools Protocol | Real Chrome read-only profile/feed/inbox tools |
| Patchright | Opt-in fallback when CDP is unavailable |
| python-docx + PyMuPDF | Local resume parsing |
| pydantic-settings | Type-safe environment config |
| structlog | Structured logs |

## Full-Power Local Mode

Clone and install everything:

```bash
git clone https://github.com/SanthaKumar-K-2004/linkedin-mcp-zero.git
cd linkedin-mcp-zero
uv sync --extra dev --extra multi --extra pdf --extra browser
```

Run checks:

```bash
uv run pytest
uv run ruff check .
uv run linkedin-mcp-zero --doctor
```

Run server:

```bash
uv run linkedin-mcp-zero
```

## Browser Tools

Start Chrome with CDP:

```bash
google-chrome --remote-debugging-port=9222
```

Then call:

```text
check_session
get_my_profile
search_people
get_feed
get_inbox
```

Opt-in Patchright fallback:

```bash
LINKEDIN_MCP_ENABLE_PATCHRIGHT_FALLBACK=true uvx mcp-server-linkedin-zero
```

## Low-Spec Mode

No Docker. No always-on browser. No heavy services.

If RAM or disk is low, the server still works:

- Public job tools keep running.
- Resume tools stay local.
- Alerts use SQLite.
- Browser tools wait until called.
- Browser auto-unloads after idle time.
- Optional extras are skipped unless installed.

Quality is not reduced; only engine loading is smarter.

## Development And Release

Build:

```bash
uv build
```

Publish a new version:

```bash
uv publish
```

Run from PyPI:

```bash
uvx mcp-server-linkedin-zero
```

Run from GitHub source:

```bash
uvx --from git+https://github.com/SanthaKumar-K-2004/linkedin-mcp-zero mcp-server-linkedin-zero
```

## Safety

This project intentionally avoids automated write actions. It does not apply to
jobs, send messages, create posts, connect with people, or modify your LinkedIn
account. Browser tools are read-only and require your own Chrome session.

Voyager is gated off by default because it is riskier than public APIs or real
browser reading.

## License

Apache 2.0. See [LICENSE](LICENSE).
