LinkedIn MCP Server

1# LinkedIn MCP Server
2 
3A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for LinkedIn. Search people, companies, and jobs, scrape profiles, and retrieve structured JSON data from any MCP-compatible AI client.
4 
5https://github.com/user-attachments/assets/50cd8629-41ee-4261-9538-40dc7d30294e
6 
7 
8Built with [FastMCP](https://github.com/PrefectHQ/fastmcp), [Patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright), and a clean hexagonal architecture.
9 
10---
11 
12## Features
13 
14| Category    | Tools                                    |
15| ----------- | ---------------------------------------- |
16| People      | `get_person_profile` · `search_people`   |
17| Companies   | `get_company_profile` · `get_company_posts` |
18| Jobs        | `get_job_details` · `search_jobs`        |
19| Browser     | `close_browser`                          |
20 
21### Person Profile Sections
22 
23The `get_person_profile` tool supports granular section scraping. Request only the sections you need:
24 
25- **Main profile** (always included) — name, headline, location, followers, connections, about, profile image
26- **Experience** — title, company, dates, duration, description, company logo
27- **Education** — school, degree, dates, description, school logo
28- **Contact info** — email, phone, websites, birthday, LinkedIn URL
29- **Interests** — people, companies, and groups followed
30- **Honors and awards** — title, issuer, description
31- **Languages** — language name and proficiency level
32- **Posts** — recent activity with reactions and timestamps
33- **Recommendations** — received and given, with author details
34 
35### Company Profile Sections
36 
37- **About** (always included) — overview, website, industry, size, headquarters, specialties, logo
38- **Posts** — recent feed posts with engagement metrics
39- **Jobs** — current open positions
40 
41### Job Search Filters
42 
43The `search_jobs` tool supports the following filters:
44 
45| Filter             | Values                                                                    |
46| ------------------ | ------------------------------------------------------------------------- |
47| `date_posted`      | `past_hour`, `past_24_hours`, `past_week`, `past_month`                   |
48| `job_type`         | `full_time`, `part_time`, `contract`, `temporary`, `internship`, `other`  |
49| `experience_level` | `entry`, `associate`, `mid_senior`, `director`, `executive`               |
50| `work_type`        | `on_site`, `remote`, `hybrid`                                             |
51| `easy_apply`       | `true` / `false`                                                          |
52| `sort_by`          | `date`, `relevance`                                                       |
53 
54---
55 
56## Prerequisites
57 
58- Python 3.12 or later
59- [uv](https://docs.astral.sh/uv/) package manager
60- A LinkedIn account for authentication
61 
62---
63 
64## Quick Start
65 
66### 1. Clone and install
67 
68```bash
69git clone https://github.com/eliasbiondo/linkedin-mcp-server.git
70cd linkedin-mcp-server
71uv sync
72```
73 
74### 2. Install browser
75 
76This project uses [Patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright) (a patched fork of Playwright) for browser automation. You need to install the browser binaries before first use:
77 
78```bash
79uv run patchright install
80```
81 
82> **Windows users:** If the command above fails with `program not found`, run instead:
83>
84> ```powershell
85> uv run python -m patchright install
86> ```
87 
88### 3. Authenticate with LinkedIn
89 
90```bash
91uv run linkedin-mcp-server --login
92```
93 
94A browser window will open. Log in to LinkedIn and the session will be persisted locally at `~/.linkedin-mcp-server/browser-data`.
95 
96### 4. Run the server
97 
98**stdio transport** (default — for Claude Desktop, Cursor, and similar clients):
99 
100```bash
101uv run linkedin-mcp-server
102```
103 
104**HTTP transport** (for remote clients, the MCP Inspector, etc.):
105 
106```bash
107uv run linkedin-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000
108```
109 
110---
111 
112## Client Integration
113 
114### Claude Desktop / Cursor
115 
116Add to your MCP configuration file:
117 
118```json
119{
120  "mcpServers": {
121    "linkedin": {
122      "command": "uv",
123      "args": [
124        "--directory", "/path/to/linkedin-mcp-server",
125        "run", "linkedin-mcp-server"
126      ]
127    }
128  }
129}
130```
131 
132### MCP Inspector
133 
134```bash
135npx @modelcontextprotocol/inspector
136```
137 
138Then connect to `http://localhost:8000/mcp` if using HTTP transport.
139 
140---
141 
142## Configuration
143 
144Configuration follows a strict precedence chain: **CLI args > environment variables > `.env` file > defaults**.
145 
146### CLI Arguments
147 
148| Argument        | Description                         | Default     |
149| --------------- | ----------------------------------- | ----------- |
150| `--transport`   | `stdio` or `streamable-http`        | `stdio`     |
151| `--host`        | Host for HTTP transport             | `127.0.0.1` |
152| `--port`        | Port for HTTP transport             | `8000`      |
153| `--log-level`   | `DEBUG`, `INFO`, `WARNING`, `ERROR` | `WARNING`   |
154| `--headless`    | Run browser in headless mode        | `true`      |
155| `--no-headless` | Show browser window (visible mode)  | —           |
156| `--login`       | Open browser for LinkedIn login     | —           |
157| `--logout`      | Clear stored credentials            | —           |
158| `--status`      | Check session status                | —           |
159 
160### Environment Variables
161 
162Create a `.env` file in the project root:
163 
164```env
165# Server
166LINKEDIN_TRANSPORT=stdio
167LINKEDIN_HOST=127.0.0.1
168LINKEDIN_PORT=8000
169LINKEDIN_LOG_LEVEL=WARNING
170 
171# Browser
172LINKEDIN_HEADLESS=true
173LINKEDIN_SLOW_MO=0
174LINKEDIN_TIMEOUT=10000
175LINKEDIN_VIEWPORT_WIDTH=1280
176LINKEDIN_VIEWPORT_HEIGHT=720
177LINKEDIN_CHROME_PATH=
178LINKEDIN_USER_AGENT=
179LINKEDIN_USER_DATA_DIR=~/.linkedin-mcp-server/browser-data
180```
181 
182---
183 
184## Architecture
185 
186The project follows a hexagonal (ports and adapters) architecture with strict layer separation:
187 
188```
189src/linkedin_mcp_server/
190├── domain/              # Core business logic — zero external dependencies
191│   ├── models/          # Data models (Person, Company, Job, Search)
192│   ├── parsers/         # HTML to structured data parsers
193│   ├── exceptions.py    # Domain exceptions
194│   └── value_objects.py # Immutable configuration and content objects
195├── ports/               # Abstract interfaces
196│   ├── auth.py          # Authentication port
197│   ├── browser.py       # Browser automation port
198│   └── config.py        # Configuration port
199├── application/         # Use cases — orchestration layer
200│   ├── scrape_person.py
201│   ├── scrape_company.py
202│   ├── scrape_job.py
203│   ├── search_people.py
204│   ├── search_jobs.py
205│   └── manage_session.py
206├── adapters/            # Concrete implementations
207│   ├── driven/          # Infrastructure adapters (browser, auth, config)
208│   └── driving/         # Interface adapters (CLI, MCP tools, serialization)
209└── container.py         # Dependency injection composition root
210```
211 
212### Design Decisions
213 
214- **Ports and adapters** — Domain logic is fully decoupled from infrastructure. The browser engine, MCP framework, and configuration source can all be swapped independently.
215- **Dependency injection** — A single `Container` class acts as the composition root and is the only place that imports concrete adapter classes.
216- **Structured JSON output** — LinkedIn HTML is parsed into typed Python dataclasses, then serialized to JSON for reliable LLM consumption.
217- **Session persistence** — Browser state is saved to disk, so authentication is required only once.
218 
219---
220 
221## Development
222 
223### Setup
224 
225```bash
226uv sync --group dev
227uv run pre-commit install
228```
229 
230### Running tests
231 
232```bash
233uv run pytest
234```
235 
236With coverage:
237 
238```bash
239uv run pytest --cov=linkedin_mcp_server
240```
241 
242### Linting and formatting
243 
244This project uses [Ruff](https://docs.astral.sh/ruff/) for both linting and formatting. Pre-commit hooks will run these automatically on each commit.
245 
246```bash
247# Lint
248uv run ruff check .
249 
250# Lint and auto-fix
251uv run ruff check . --fix
252 
253# Format
254uv run ruff format .
255```
256 
257---
258 
259## License
260 
261This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
262 
263---
264 
265## Contributing
266 
267Contributions are welcome. Please read the [contributing guide](CONTRIBUTING.md) for details on the development workflow and submission process.
268 
269---
270 
271## Disclaimer
272 
273This tool is intended for personal and educational use. Scraping LinkedIn may violate their Terms of Service. Use responsibly and at your own risk. The authors are not responsible for any misuse or consequences arising from the use of this software.
274