linkedin-mcp-server

2720 GitHub stars recorded

Contributions are welcome! See CONTRIBUTING.md for architecture guidelines and checklists. Please open an issue first to discuss the feature or bug fix before submitting a PR.

Prerequisites: Git and uv installed

Installation

# 1. Clone repository
git clone https://github.com/stickerdaniel/linkedin-mcp-server
cd linkedin-mcp-server

# 2. Install UV package manager (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. Install dependencies
uv sync
uv sync --group dev

# 4. Install pre-commit hooks
uv run pre-commit install

# 5. Start the server
uv run -m linkedin_mcp_server

The local server uses the same managed-runtime flow as MCPB and uvx: it prepares the Patchright Chromium browser cache in the background and opens LinkedIn login on the first auth-requiring tool call. You can still run uv run -m linkedin_mcp_server --login when you want to create the session explicitly.

Local Setup Help

CLI Options:

• --login - Open browser to log in and save persistent profile
• --import-from-browser [BROWSER] - Import a LinkedIn session from a locally logged-in Chromium browser (chrome, chromium, brave, edge, , , , , , or ). Bare flag picks , which auto-selects the most recently used browser with a live LinkedIn session.

Note: Most CLI options have environment variable equivalents. See .env.example for details.

HTTP Mode Example (for web-based MCP clients):

uv run -m linkedin_mcp_server --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp

Claude Desktop:

{
  "mcpServers": {
    "mcp-server-linkedin": {
      "command": "uv",
      "args": ["--directory", "/path/to/linkedin-mcp-server", "run", "-m", "linkedin_mcp_server"]
    }
  }
}

stdio is used by default for this config.

Login issues:

• Make sure you have only one active LinkedIn session at a time
• LinkedIn may require a login confirmation in the LinkedIn mobile app for --login
• LinkedIn may show a captcha challenge during login. The --login command opens a browser where you can solve it manually.

Scraping issues:

• Use --no-headless to see browser actions and debug scraping problems
• Add --log-level DEBUG to see more detailed logging

Session issues:

• Browser profile is stored at ~/.linkedin-mcp/profile/
• Use --logout to clear the profile and start fresh

Python/Patchright issues:

• Check Python version: python --version (should be 3.12+)
• Reinstall Patchright: uv run patchright install chromium
• Reinstall dependencies: uv sync --reinstall

Timeout issues:

• Page operations failing (elements not found, navigation hangs): increase the browser page-op timeout — --timeout 10000 or TIMEOUT=10000 (milliseconds, default 5000).
• Entire tool calls timing out (e.g. multi-section profiles, cold-start Chromium, slow containers): increase the per-tool execution timeout — --tool-timeout 300 or TOOL_TIMEOUT=300 (seconds, default 180).
• First tool call with no session: if a locally logged-in browser has a live LinkedIn session, the server auto-imports it (see AUTO_IMPORT_FROM_BROWSER / --auto-import) instead of forcing a manual login. On macOS the keychain may prompt once for Safe Storage access. If no importable browser session exists, it falls back to opening a login window and waits up to LOGIN_INLINE_WAIT seconds (default 25, max 45; --login-inline-wait) so a quick sign-in resolves in one call. If the wait elapses, the tool returns a pending signal and the model retries in about 30 seconds. Neither the auto-import nor the inline wait applies under Docker or when the server is bound to a non-loopback HTTP host; create the session on the host with --login.
• Users on slow connections may need higher values for either.

Custom Chrome path:

• If Chrome is installed in a non-standard location, use --chrome-path /path/to/chrome
• Can also set via environment variable: CHROME_PATH=/path/to/chrome

[!IMPORTANT] FAQ

Is this safe to use? Will I get banned? This tool controls a real browser session; it doesn't exploit undocumented APIs or bypass authentication. LinkedIn's User Agreement prohibits automated access, and accounts using automated tools can be restricted or banned. Use at your own risk; there is no guarantee of account safety. If you encounter any issues, let me know in the Discussions.

What if my agents execute too many actions? Tool calls run sequentially through a queue. You are responsible for the volume of automation you run; use it sparingly and prompt your agents responsibly.

Docker Setup Help

Transport Modes:

• Default (stdio): Standard communication for local MCP servers
• Streamable HTTP: For a web-based MCP server
• If no transport is specified, the server defaults to stdio
• An interactive terminal without explicit transport shows a chooser prompt

CLI Options:

• --log-level {DEBUG,INFO,WARNING,ERROR} - Set logging level (default: WARNING)
• --transport {stdio,streamable-http} - Optional: force transport mode (default: stdio)
• --host HOST - HTTP server host (default: 127.0.0.1)
• --port PORT - HTTP server port (default: 8000)
• --path PATH - HTTP server path (default: /mcp)
• --logout - Clear all stored LinkedIn auth state, including source and derived runtime profiles
• --timeout MS - Browser timeout for page operations in milliseconds (default: 5000)
• --tool-timeout SECONDS - Per-tool MCP execution timeout in seconds (default: 180.0). Increase further for heavy scrapes / cold-start Chromium / slow networks.
• --login-timeout SECONDS - Manual login wait timeout in seconds (default: 1800; 0 = no limit). How long the --login browser waits for you to finish signing in.
• --login-inline-wait SECONDS - Bounded inline wait for a tool call to resume after login completes, in seconds (default: 25, max 45; 0 = return immediately).
• --auto-import / --no-auto-import - Enable or disable auto-import of a session from a locally logged-in browser on the first no-session tool call (before falling back to manual login). Auto-import is on by default across interactive and non-interactive desktop runs; pass --no-auto-import (or AUTO_IMPORT_FROM_BROWSER=false) to require --login / --import-from-browser instead. No effect under Docker or on a non-loopback HTTP bind. On macOS the keychain may prompt once for Safe Storage access.
• --user-data-dir PATH - Path to persistent browser profile directory (default: ~/.linkedin-mcp/profile)
• --chrome-path PATH - Path to Chrome/Chromium executable (rarely needed in Docker)

[!NOTE] --login and --no-headless are not available in Docker (no display server). Use the uvx setup to create profiles.

HTTP Mode Example (for web-based MCP clients):

docker run -it --rm \
  -v ~/.linkedin-mcp:/home/pwuser/.linkedin-mcp \
  -p 8080:8080 \
  stickerdaniel/linkedin-mcp-server:latest \
  --transport streamable-http --host 0.0.0.0 --port 8080 --path /mcp

Runtime server logs are emitted by FastMCP/Uvicorn.

Test with mcp inspector:

1. Install and run mcp inspector bunx @modelcontextprotocol/inspector
2. Click pre-filled token url to open the inspector in your browser
3. Select Streamable HTTP as Transport Type
4. Set URL to http://localhost:8080/mcp
5. Connect
6. Test tools

Docker issues:

• Make sure Docker is installed
• Check if Docker is running: docker ps

Login issues:

• Make sure you have only one active LinkedIn session at a time
• LinkedIn may require a login confirmation in the LinkedIn mobile app for --login
• LinkedIn may show a captcha challenge during login. Run uvx mcp-server-linkedin@latest --login which opens a browser where you can solve captchas manually. See the uvx setup for prerequisites.
• If Docker auth becomes stale after you re-login on the host, restart Docker once so it can fresh-bridge from the new source session generation.

Timeout issues:

• Page operations failing (elements not found, navigation hangs): increase the browser page-op timeout — --timeout 10000 or TIMEOUT=10000 (milliseconds, default 5000).
• Entire tool calls timing out (e.g. multi-section profiles, cold-start Chromium, slow containers): increase the per-tool execution timeout — --tool-timeout 300 or TOOL_TIMEOUT=300 (seconds, default 180).
• First tool call with no session: if a locally logged-in browser has a live LinkedIn session, the server auto-imports it (see AUTO_IMPORT_FROM_BROWSER / --auto-import) instead of forcing a manual login. On macOS the keychain may prompt once for Safe Storage access. If no importable browser session exists, it falls back to opening a login window and waits up to LOGIN_INLINE_WAIT seconds (default 25, max 45; --login-inline-wait) so a quick sign-in resolves in one call. If the wait elapses, the tool returns a pending signal and the model retries in about 30 seconds. Neither the auto-import nor the inline wait applies under Docker or when the server is bound to a non-loopback HTTP host; create the session on the host with --login.
• Users on slow connections may need higher values for either.

Custom Chrome path:

• If Chrome is installed in a non-standard location, use --chrome-path /path/to/chrome
• Can also set via environment variable: CHROME_PATH=/path/to/chrome