How stickerdaniel/linkedin-mcp-server works
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: cli_main.py CLI modes · person.py LinkedIn domain tools · server.py MCP server assembly · session_state.py Persisted session state
Components 21
Startup & configuration
- Python entry points · Selects CLI or module startup.
linkedin_mcp_server/__main__.py - CLI modes · Runs server, login, logout, status, and cookie import.
linkedin_mcp_server/cli_main.py - Validated configuration
linkedin_mcp_server/config/loaders.py - Runtime bootstrap · Prepares managed browser and cache state.
linkedin_mcp_server/bootstrap.py
MCP tool service
- MCP server assembly · Serves stdio by default or streamable HTTP.
linkedin_mcp_server/server.py - Sequential tool middleware · Serializes calls against one mutable browser session.
linkedin_mcp_server/sequential_tool_middleware.py - LinkedIn domain tools · People, company, jobs, feed/posts, and messaging operations.
linkedin_mcp_server/tools/person.py - Actionable errors · Classifies browser and extraction failures for MCP clients.
linkedin_mcp_server/error_handler.py
Auth & browser ownership
- Browser authentication · Creates and validates persisted authenticated browser state.
linkedin_mcp_server/authentication.py - Browser cookie import · Discovers, extracts, decrypts, validates, and imports local browser sessions.
linkedin_mcp_server/browser_import/orchestrate.py - Persisted session state
linkedin_mcp_server/session_state.py - Profile claim & lease · Safely owns, cleans up, and leases the browser profile.
linkedin_mcp_server/profile_lease.py - Cross-process browser coordination · Elects exclusive browser owner and proxies waiting processes.
linkedin_mcp_server/daemon_election.py
Browser automation & extraction
- Chromium launcher · Launches Patchright Chromium with runtime safety controls.
linkedin_mcp_server/browser_launch.py - Browser controller
linkedin_mcp_server/drivers/browser.py - Navigation primitives
linkedin_mcp_server/scraping/connection.py - Page extraction · Parses LinkedIn pages into tool results.
linkedin_mcp_server/scraping/extractor.py
Other components
- LinkedIn website
- AI MCP clients
- FastMCP / Uvicorn · Provides optional streamable HTTP transport.
- Docker deployment · Uses a derived runtime profile instead of the host browser profile.
Dockerfile
Connections 26
- 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