# stickerdaniel/linkedin-mcp-server architecture

> Architecture diagram of the GitHub repository stickerdaniel/linkedin-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stickerdaniel/linkedin-mcp-server
- Repository: https://github.com/stickerdaniel/linkedin-mcp-server

## Overview

#### Purpose and Entry Points
A Python 3.12+ MCP server that exposes LinkedIn reading and selected writing operations to AI clients through the user’s authenticated browser session, rather than a LinkedIn API. Primary executable paths are `linkedin_mcp_server/__main__.py` and `linkedin_mcp_server/cli_main.py`; server assembly and MCP transport are in `linkedin_mcp_server/server.py`. It supports stdio by default and FastMCP/Uvicorn streamable HTTP optionally.

#### Startup, Configuration, and Roles
CLI parsing chooses operational modes: run server, login/logout/status, browser-cookie import, and transport settings. Configuration is loaded and validated before runtime initialization through `linkedin_mcp_server/config/loaders.py` and `linkedin_mcp_server/config/schema.py`. `linkedin_mcp_server/bootstrap.py` prepares the managed runtime/browser cache; `linkedin_mcp_server/server_role.py` distinguishes normal server, login, and related process roles.

#### MCP Tool Boundary
MCP-facing tool groups are partitioned by LinkedIn domain: people, companies, jobs, feed/posts, and messaging in `linkedin_mcp_server/tools/person.py`, `linkedin_mcp_server/tools/company.py`, and `linkedin_mcp_server/tools/messaging.py`. The server registers these tools, applies whole-tool timeouts/error translation, and routes requests into browser-driven workflows. `linkedin_mcp_server/sequential_tool_middleware.py` serializes calls within a process, protecting a single mutable browser session and limiting automation concurrency.

#### Authentication and Session Lifecycle
Authentication is browser-based: explicit login creates persisted profile/cookie state; local Chromium-family browser sessions may be discovered, decrypted where supported, extracted, validated, and imported. Main boundaries are `linkedin_mcp_server/authentication.py`, `linkedin_mcp_server/browser_import/orchestrate.py`, and `linkedin_mcp_server/session_state.py`. Profile directory ownership, safe cleanup, and cross-process claims are handled by `linkedin_mcp_server/profile_claim.py` and `linkedin_mcp_server/profile_lease.py`. Docker uses a derived runtime profile/session model rather than directly opening the host profile.

#### Browser Runtime and Multi-Process Coordination
Patchright Chromium is launched and controlled through `linkedin_mcp_server/browser_launch.py`, `linkedin_mcp_server/drivers/browser.py`, and `linkedin_mcp_server/core/browser.py`. Browser fingerprint/version safety, proxy handling, headless/viewer variants, and browser downgrade protections sit around this boundary. Separate MCP processes coordinate exclusive browser ownership using lock, election, liveness, descriptor, and proxy modules, notably `linkedin_mcp_server/daemon_election.py`, `linkedin_mcp_server/daemon_lock.py`, and `linkedin_mcp_server/daemon_proxy.py`; waiting processes hand off rather than concurrently manipulating the profile.

#### LinkedIn Extraction Flow
A tool acquires the browser lease, ensures a valid authenticated session, navigates LinkedIn pages, then invokes page-specific extraction. Shared scraping primitives—connection/navigation, field parsing, and link metadata—live in `linkedin_mcp_server/scraping/connection.py`, `linkedin_mcp_server/scraping/extractor.py`, and `linkedin_mcp_server/scraping/fields.py`. Results return through the MCP tool boundary; failures are classified and made actionable through `linkedin_mcp_server/error_handler.py` and `linkedin_mcp_server/error_diagnostics.py`.

#### Deployment and External Dependencies
The runtime depends on FastMCP/Uvicorn for MCP transports, Patchright/Chromium for browser automation, and LinkedIn as the third-party web service. It runs locally via `uvx`/Python or in Docker using `Dockerfile`, `docker-compose.yml`, and `docker-entrypoint.sh`. Docker login can expose a token-protected browser viewer; HTTP deployment is intended for loopback binding and relies on host restrictions rather than built-in endpoint authentication.

Main entry points: [`linkedin_mcp_server/cli_main.py`](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/cli_main.py) (CLI modes), [`linkedin_mcp_server/tools/person.py`](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/tools/person.py) (LinkedIn domain tools), [`linkedin_mcp_server/server.py`](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/server.py) (MCP server assembly), [`linkedin_mcp_server/session_state.py`](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/session_state.py) (Persisted session state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup &amp; configuration"]
  node_entry["Python entry points<br/>executable<br/>[__main__.py]"]
  node_cli["CLI modes<br/>command router<br/>[cli_main.py]"]
  node_config["Validated configuration<br/>config loader<br/>[loaders.py]"]
  node_bootstrap["Runtime bootstrap<br/>runtime setup<br/>[bootstrap.py]"]
end

subgraph group_mcp["MCP tool service"]
  node_server["MCP server assembly<br/>MCP transport host<br/>[server.py]"]
  node_tool_middleware["Sequential tool middleware<br/>concurrency guard"]
  node_tools["LinkedIn domain tools<br/>MCP tools<br/>[person.py]"]
  node_errors["Actionable errors<br/>error translation<br/>[error_handler.py]"]
end

subgraph group_session["Auth &amp; browser ownership"]
  node_auth["Browser authentication<br/>session auth<br/>[authentication.py]"]
  node_browser_import["Browser cookie import<br/>session importer<br/>[orchestrate.py]"]
  node_session_state[("Persisted session state<br/>profile state<br/>[session_state.py]")]
  node_profile_lease["Profile claim &amp; lease<br/>profile ownership<br/>[profile_lease.py]"]
  node_daemon_coordination["Cross-process browser coordination<br/>daemon election<br/>[daemon_election.py]"]
end

subgraph group_browser["Browser automation &amp; extraction"]
  node_browser_launch["Chromium launcher<br/>browser runtime<br/>[browser_launch.py]"]
  node_browser_driver["Browser controller<br/>Patchright driver<br/>[browser.py]"]
  node_scraping_connection["Navigation primitives<br/>scraping connection<br/>[connection.py]"]
  node_extractor["Page extraction<br/>scraping extractor<br/>[extractor.py]"]
end

node_linkedin{{"LinkedIn website<br/>third-party service"}}
node_mcp_clients(("AI MCP clients"))
node_runtime_deps["FastMCP / Uvicorn<br/>transport runtime"]
node_docker["Docker deployment<br/>container runtime"]

node_entry -->|"starts"| node_cli
node_cli -->|"loads"| node_config
node_cli -->|"initializes"| node_bootstrap
node_cli -->|"runs server mode"| node_server
node_cli -->|"runs login/status"| node_auth
node_cli -->|"runs import"| node_browser_import
node_config -->|"configures"| node_server
node_bootstrap -->|"prepares"| node_session_state
node_mcp_clients -->|"MCP requests"| node_server
node_runtime_deps -->|"hosts HTTP transport"| node_server
node_server -->|"wraps"| node_tool_middleware
node_tool_middleware -->|"serializes calls"| node_tools
node_tools -->|"acquires browser lease"| node_profile_lease
node_tools -->|"drives workflow"| node_scraping_connection
node_tools -->|"translates failures"| node_errors
node_auth -->|"persists"| node_session_state
node_browser_import -->|"imports into"| node_session_state
node_profile_lease -->|"coordinates ownership"| node_daemon_coordination
node_profile_lease -->|"protects profile"| node_session_state
node_daemon_coordination -->|"grants exclusive control"| node_browser_launch
node_browser_launch -->|"launches"| node_browser_driver
node_scraping_connection -->|"uses"| node_browser_driver
node_scraping_connection -->|"hands page data to"| node_extractor
node_browser_driver -->|"automates"| node_linkedin
node_extractor -->|"returns structured results"| node_tools
node_docker -->|"runs with derived profile"| node_bootstrap

click node_entry "https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/__main__.py"
click node_cli "https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/cli_main.py"
click node_config "https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/config/loaders.py"
click node_bootstrap "https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/bootstrap.py"
click node_server "https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/server.py"
click node_tool_middleware "https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/sequential_tool_middleware.py"
click node_tools "https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/tools/person.py"
click node_auth "https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/authentication.py"
click node_browser_import "https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/browser_import/orchestrate.py"
click node_session_state "https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/session_state.py"
click node_profile_lease "https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/profile_lease.py"
click node_daemon_coordination "https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/daemon_election.py"
click node_browser_launch "https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/browser_launch.py"
click node_browser_driver "https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/drivers/browser.py"
click node_scraping_connection "https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/scraping/connection.py"
click node_extractor "https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/scraping/extractor.py"
click node_errors "https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/error_handler.py"
click node_docker "https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_cli,node_config,node_bootstrap toneBlue
class node_server,node_tool_middleware,node_tools,node_errors toneAmber
class node_auth,node_browser_import,node_session_state,node_profile_lease,node_daemon_coordination toneMint
class node_browser_launch,node_browser_driver,node_scraping_connection,node_extractor toneRose
class node_linkedin,node_mcp_clients,node_runtime_deps,node_docker toneNeutral
```

## Components

### Startup & configuration

- [Python entry points](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/__main__.py): executable · Selects CLI or module startup. · `linkedin_mcp_server/__main__.py`
- [CLI modes](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/cli_main.py): command router · Runs server, login, logout, status, and cookie import. · `linkedin_mcp_server/cli_main.py`
- [Validated configuration](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/config/loaders.py): config loader · `linkedin_mcp_server/config/loaders.py`
- [Runtime bootstrap](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/bootstrap.py): runtime setup · Prepares managed browser and cache state. · `linkedin_mcp_server/bootstrap.py`

### MCP tool service

- [MCP server assembly](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/server.py): MCP transport host · Serves stdio by default or streamable HTTP. · `linkedin_mcp_server/server.py`
- [Sequential tool middleware](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/sequential_tool_middleware.py): concurrency guard · Serializes calls against one mutable browser session. · `linkedin_mcp_server/sequential_tool_middleware.py`
- [LinkedIn domain tools](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/tools/person.py): MCP tools · People, company, jobs, feed/posts, and messaging operations. · `linkedin_mcp_server/tools/person.py`
- [Actionable errors](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/error_handler.py): error translation · Classifies browser and extraction failures for MCP clients. · `linkedin_mcp_server/error_handler.py`

### Auth & browser ownership

- [Browser authentication](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/authentication.py): session auth · Creates and validates persisted authenticated browser state. · `linkedin_mcp_server/authentication.py`
- [Browser cookie import](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/browser_import/orchestrate.py): session importer · Discovers, extracts, decrypts, validates, and imports local browser sessions. · `linkedin_mcp_server/browser_import/orchestrate.py`
- [Persisted session state](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/session_state.py): profile state · `linkedin_mcp_server/session_state.py`
- [Profile claim & lease](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/profile_lease.py): profile ownership · Safely owns, cleans up, and leases the browser profile. · `linkedin_mcp_server/profile_lease.py`
- [Cross-process browser coordination](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/daemon_election.py): daemon election · Elects exclusive browser owner and proxies waiting processes. · `linkedin_mcp_server/daemon_election.py`

### Browser automation & extraction

- [Chromium launcher](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/browser_launch.py): browser runtime · Launches Patchright Chromium with runtime safety controls. · `linkedin_mcp_server/browser_launch.py`
- [Browser controller](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/drivers/browser.py): Patchright driver · `linkedin_mcp_server/drivers/browser.py`
- [Navigation primitives](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/scraping/connection.py): scraping connection · `linkedin_mcp_server/scraping/connection.py`
- [Page extraction](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/linkedin_mcp_server/scraping/extractor.py): scraping extractor · Parses LinkedIn pages into tool results. · `linkedin_mcp_server/scraping/extractor.py`

### Other components

- **LinkedIn website**: third-party service
- **AI MCP clients**: client
- **FastMCP / Uvicorn**: transport runtime · Provides optional streamable HTTP transport.
- [Docker deployment](https://github.com/stickerdaniel/linkedin-mcp-server/blob/main/Dockerfile): container runtime · Uses a derived runtime profile instead of the host browser profile. · `Dockerfile`

## Connections

- Python entry points → CLI modes: starts
- CLI modes → Validated configuration: loads
- CLI modes → Runtime bootstrap: initializes
- CLI modes → MCP server assembly: runs server mode
- CLI modes → Browser authentication: runs login/status
- CLI modes → Browser cookie import: runs import
- Validated configuration → MCP server assembly: configures
- Runtime bootstrap → Persisted session state: prepares
- AI MCP clients → MCP server assembly: MCP requests
- FastMCP / Uvicorn → MCP server assembly: hosts HTTP transport
- MCP server assembly → Sequential tool middleware: wraps
- Sequential tool middleware → LinkedIn domain tools: serializes calls
- LinkedIn domain tools → Profile claim & lease: acquires browser lease
- LinkedIn domain tools → Navigation primitives: drives workflow
- LinkedIn domain tools → Actionable errors: translates failures
- Browser authentication → Persisted session state: persists
- Browser cookie import → Persisted session state: imports into
- Profile claim & lease → Cross-process browser coordination: coordinates ownership
- Profile claim & lease → Persisted session state: protects profile
- Cross-process browser coordination → Chromium launcher: grants exclusive control
- Chromium launcher → Browser controller: launches
- Navigation primitives → Browser controller: uses
- Navigation primitives → Page extraction: hands page data to
- Browser controller → LinkedIn website: automates
- Page extraction → LinkedIn domain tools: returns structured results
- Docker deployment → Runtime bootstrap: runs with derived profile
