Metadata-Version: 2.4
Name: mcp-server-linkedin-zero
Version: 0.2.0
Summary: Token-optimized, public-first 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

**A public-first MCP server for LinkedIn jobs, resumes, matching, alerts, exports, and opt-in read-only browser intelligence.**

No Docker required · Claude Desktop ready · Claude Code ready · Low-RAM friendly · 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>

## Install In One Command

| Client | Command |
|---|---|
| Claude Desktop | `uvx --refresh-package mcp-server-linkedin-zero mcp-server-linkedin-zero --install-client claude-desktop` |
| Claude Code | `uvx --refresh-package mcp-server-linkedin-zero mcp-server-linkedin-zero --install-client claude-code` |
| Cursor | `uvx mcp-server-linkedin-zero --install-client cursor` |
| VS Code | `uvx mcp-server-linkedin-zero --install-client vscode` |
| Any stdio client | `uvx mcp-server-linkedin-zero` |

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

Verify after install:

```bash
uvx --refresh-package mcp-server-linkedin-zero mcp-server-linkedin-zero --verify-client claude-desktop
```

Browser mode:

```bash
uvx --refresh-package mcp-server-linkedin-zero mcp-server-linkedin-zero --install-client claude-desktop --with-extra browser
```

## Tool Inventory

### Default Tools: 23 Working

These work without LinkedIn login or browser setup.

| # | Tool | Feature | Risk |
|---:|---|---|---|
| 1 | `search_jobs` | Search public LinkedIn jobs | Public no-login |
| 2 | `search_jobs_multi` | Multi-board search; LinkedIn fallback by default | Public no-login |
| 3 | `get_job_details` | Full public job details | Public no-login |
| 4 | `get_company_jobs` | Public jobs for a company | Public no-login |
| 5 | `get_company_profile` | Company signals inferred from public jobs | Public no-login |
| 6 | `search_companies` | Company discovery from public job data | Public no-login |
| 7 | `get_job_salary` | Salary extraction from job detail pages | Public no-login |
| 8 | `get_job_trends` | Role/location hiring trends | Public no-login |
| 9 | `get_industry_insights` | Market signals for an industry | Public no-login |
| 10 | `search_jobs_advanced` | Job search with filters | Public no-login |
| 11 | `analyze_resume` | Local PDF/DOCX/text resume parsing | Local |
| 12 | `get_resume_insights` | Local skill gaps and suggestions | Local |
| 13 | `match_jobs_to_resume` | Rank public jobs against a resume | Local/public |
| 14 | `compare_jobs` | Compare selected jobs | Local/public |
| 15 | `export_jobs` | Export jobs to CSV/JSON/XLSX | Local |
| 16 | `save_job_alert` | Save a recurring search | Local |
| 17 | `get_saved_alerts` | List saved searches | Local |
| 18 | `check_saved_alerts` | Run alerts and find new matches | Local/public |
| 19 | `get_engine_status` | Runtime, engine, token, cache status | Local |
| 20 | `get_help` | Tool documentation | Local |
| 21 | `get_usage_stats` | Local response-size/token estimates | Local |
| 22 | `get_tool_usage_summary` | Aggregate local usage by tool | Local |
| 23 | `reset_usage_stats` | Clear local usage metrics | Local |

### Browser Tools: +11

Enable with `--with-extra browser` or `--enable-browser`. These are read-only,
but they use your logged-in browser session.

| # | Tool | Feature |
|---:|---|---|
| 24 | `get_my_profile` | Read your profile |
| 25 | `get_person_profile` | Read a public/person profile page |
| 26 | `search_people` | People search through browser |
| 27 | `get_my_connections` | Read your connection list |
| 28 | `get_inbox` | Recent conversations list |
| 29 | `get_conversation` | Read a conversation thread |
| 30 | `get_feed` | Read home feed posts |
| 31 | `get_notifications` | Read notifications |
| 32 | `get_sidebar_profiles` | Suggested/sidebar profiles |
| 33 | `get_company_employees` | Company people page |
| 34 | `check_session` | Check CDP/login readiness |

### Gated Private-Risk Tool: +1

| # | Tool | Feature |
|---:|---|---|
| 35 | `get_profile_voyager` | Voyager/private API placeholder, disabled by default |

Default mode exposes **23 usable tools**: 22 core local/public tools plus
`search_jobs_multi`, which falls back to LinkedIn-only results unless the
`multi` extra is installed. Browser tools appear only with `--enable-browser` or
`--with-extra browser` in an installed client config. Voyager/private API mode is
hidden unless explicitly enabled.

Tool counts:

| Mode | Exposed Tools | Notes |
|---|---:|---|
| Default | 23 | Safe local/public tools; no LinkedIn login required |
| Browser enabled | 34 | Adds 11 read-only browser tools; needs Chrome/CDP login |
| Browser + Voyager | 35 | Adds gated private-API placeholder |

## Safety Model

| Mode | Label | Account Risk |
|---|---|---|
| Local resume/alerts/exports | `local_zero_account_risk` | None |
| Public no-login job data | `public_no_login_read_only` | No LinkedIn login required |
| Browser tools | `browser_readonly_account_risk` | Opt-in account risk |
| Voyager/private API | `disabled_private_api_risk` | Disabled by default |

No tool posts, likes, connects, follows, applies, or sends messages.

## Browser Mode

Install browser dependencies into the isolated `uvx` runtime:

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

Start Chrome with remote debugging and log in manually:

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

Then call `check_session` from your MCP client.

Global Playwright installs do not count for `uvx`; use `--with-extra browser`.

## Token Usage Tracking

Claude Desktop has no built-in per-MCP token counter. This server provides a
privacy-safe tracker instead:

- Estimated tokens: `ceil(response_chars / 4)`, always on.
- Exact-style counts: optional Anthropic `/v1/messages/count_tokens`.
- Full tool responses are not stored in the metrics database.
- Exact-style counting sends the counted response text to Anthropic only when
  `ANTHROPIC_API_KEY` and `LINKEDIN_MCP_EXACT_TOKEN_COUNT=true` are both set.

Enable exact-style counting:

```bash
ANTHROPIC_API_KEY=sk-ant-... LINKEDIN_MCP_EXACT_TOKEN_COUNT=true uvx mcp-server-linkedin-zero
```

Use a different token-count model if needed:

```bash
LINKEDIN_MCP_TOKEN_COUNT_MODEL=claude-sonnet-4-5
```

Usage tools:

```text
get_usage_stats
get_tool_usage_summary
reset_usage_stats
```

Avoid terminal transcript logging as a token strategy; it can expose private
profile, inbox, resume, or job data.

## Client Config

Print without editing files:

```bash
uvx mcp-server-linkedin-zero --print-config --client claude-desktop
uvx mcp-server-linkedin-zero --print-config --client vscode
```

Claude Desktop and Cursor use:

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

VS Code uses:

```json
{
  "servers": {
    "linkedin-zero": {
      "command": "/absolute/path/to/uvx",
      "args": ["mcp-server-linkedin-zero"]
    }
  }
}
```

## Doctor

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

Checks OS, Python, RAM, disk, Chrome, CDP URL, display state, optional extras,
and recommended mode.

## Development

```bash
uv sync --extra dev
uv run --extra dev ruff check .
uv run --extra dev pytest
uv build
```

Publish only the new version files:

```bash
UV_PUBLISH_TOKEN=... uv publish dist/mcp_server_linkedin_zero-0.2.0*
```
