LinkedIn MCP Server (TypeScript / Bun)

<p align="left"> <a href="https://www.npmjs.com/package/linkedin-mcp-server-ts" target="_blank"><img src="https://img.shields.io/npm/v/linkedin-mcp-server-ts?color=cb3837&logo=npm" alt="npm version"></a> <a href="https://bun.sh" target="_blank"><img src="https://img.shields.io/badge/Runtime-Bun%201.2+-fbf0df?logo=bun&logoColor=black" alt="Bun Runtime"></a> <a href="https://www.typescriptlang.org/" target="_blank"><img src="https://img.shields.io/badge/Language-TypeScript%207-3178c6?logo=typescript&logoColor=white" alt="TypeScript"></a> <a href="https://modelcontextprotocol.io/" target="_blank"><img src="https://img.shields.io/badge/MCP-SDK%202.0-8a2be2" alt="Model Context Protocol"></a> <a href="https://github.com/joaovjo/linkedin-mcp-server-ts/blob/main/LICENSE" target="_blank"><img src="https://img.shields.io/badge/License-MIT-3fb950" alt="License: MIT"></a> <a href="https://biomejs.dev" target="_blank"><img src="https://img.shields.io/badge/Linter-Biome-60a5fa?logo=biome&logoColor=white" alt="Biome"></a> </p>

Disclaimer: This is an independent open-source project. It is not affiliated with, sponsored by, or endorsed by LinkedIn Corporation or Microsoft Corporation. "LinkedIn" is a registered trademark of LinkedIn Corporation and is used purely descriptively.

A Model Context Protocol (MCP) server for LinkedIn scraping and automation, written in TypeScript and executed directly on Bun.

It gives AI assistants (Claude Desktop, Cursor, OpenCode, VS Code, Windsurf, Antigravity) 19 MCP tools to inspect profiles, search jobs and companies, manage messages, and fetch feed updates through your existing authenticated browser session.

---

Why TypeScript + Bun

linkedin-mcp-server-ts is a native TypeScript port of stickerdaniel/linkedin-mcp-server. Moving from Python to Bun reduced baseline memory usage and removed the need for separate browser daemon layers.

• Fast startup: Bun executes TypeScript directly without build steps or transpilation passes.
• Direct CDP communication: connects directly to Chromium instances via Chrome DevTools Protocol and Bun.WebView.
• Full schema parity: matching tool signatures, Zod validation schemas, and JSON envelope output corresponding to the original Python server.
• Shared session storage: reads and writes cookies to ~/.linkedin-mcp/profile for complete interoperability.

Architecture Comparison

Feature	Python Version (mcp-server-linkedin)	TypeScript / Bun Version (linkedin-mcp-server-ts)
Runtime	Python 3.10+ (uv / uvx)	Bun 1.2+ (bun / bunx)
Language	Python (fastmcp)	TypeScript 5.8+ (@modelcontextprotocol/server v2)
Browser Engine	Patchright Chromium fork	Native Bun.WebView + Direct Chrome DevTools Protocol (CDP)
Memory Baseline	~150MB+	~30-60MB
Transports	stdio, streamable-http	stdio, streamable-http (via native Bun.serve)
Session Directory	~/.linkedin-mcp/profile	~/.linkedin-mcp/profile (Shared & Interoperable)
Validation	Pydantic	Zod schemas
Tool Count	19 tools	19 tools

---

Available MCP Tools (19 Tools)

Tool	Category	Description	Access
get_person_profile	People	Extract profile details with granular sections (experience, education, skills, projects, certifications, posts)	Read-Only
get_my_profile	People	Extract the authenticated user's own profile	Read-Only
search_people	People	Search people by keywords, location, connection degree (F=1st, S=2nd, O=3rd+), and current company	Read-Only
connect_with_person	People	Send a connection invitation or accept an incoming request with an optional note	Write / Action
get_sidebar_profiles	People	Extract sidebar recommendations ("People you may know", "More profiles")	Read-Only
get_company_profile	Company	Extract company details, about section, posts, jobs, and numeric URN IDs	Read-Only
get_company_posts	Company	Retrieve recent company feed posts	Read-Only
search_companies	Company	Search companies by keyword	Read-Only
get_company_employees	Company	List company employees from the /people/ tab with optional filters	Read-Only
get_job_details	Jobs	Fetch full job descriptions, criteria, and company metadata	Read-Only
search_jobs	Jobs	Search jobs by keywords, location, date posted, job type, work type, and easy apply	Read-Only
get_saved_jobs	Jobs	Retrieve the authenticated user's saved job listings	Read-Only
get_inbox	Messaging	List recent conversation threads from the messaging inbox	Read-Only
get_conversation	Messaging	Read messages from a thread by username or thread_id	Read-Only
search_conversations	Messaging	Search messaging threads by keyword	Read-Only
send_message	Messaging	Send a LinkedIn direct message (requires confirm_send: true confirmation)	Write / Action
get_feed	Feed	Retrieve recent posts from your home timeline	Read-Only
search_posts	Feed	Global search across LinkedIn posts with recency filters	Read-Only
close_session	Session	Terminate the browser session and release background process handles	Write / Action

---

Quickstart

Prerequisites

1. Install Bun (v1.2 or higher):

   # Windows (PowerShell)
   powershell -c "irm bun.sh/install.ps1 | iex"
   
   # macOS / Linux
   curl -fsSL https://bun.sh/install | bash
   

2. Google Chrome or Chromium: installed on the host system.

One-Command Execution (bunx)

Run the server directly without cloning or manual builds:

bunx linkedin-mcp-server-ts

Local Clone & Development Setup

# Clone the repository
git clone https://github.com/joaovjo/linkedin-mcp-server-ts.git
cd linkedin-mcp-server-ts

# Install dependencies
bun install

# Start in stdio mode (default for MCP clients)
bun run start

# Start in HTTP mode (for web MCP debugging)
bun run dev

---

MCP Client Configuration

1. Claude Desktop

Add to claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "linkedin": {
      "command": "bunx",
      "args": ["linkedin-mcp-server-ts"]
    }
  }
}

When running from a local checkout:

{
  "mcpServers": {
    "linkedin": {
      "command": "bun",
      "args": ["run", "src/index.ts"],
      "cwd": "D:/linkedin/linkedin-mcp-server-ts"
    }
  }
}

---

2. Cursor

Add to your project's .cursor/mcp.json or Global Settings:

{
  "mcpServers": {
    "linkedin": {
      "command": "bunx",
      "args": ["linkedin-mcp-server-ts"]
    }
  }
}

---

3. OpenCode

Add to opencode.json (or ~/.config/opencode/opencode.json):

{
  "mcp": {
    "linkedin": {
      "type": "stdio",
      "command": "bunx",
      "args": ["linkedin-mcp-server-ts"]
    }
  }
}

---

4. Antigravity / Windsurf / VS Code (Cline / Roo Code)

Add to mcp_config.json:

{
  "mcpServers": {
    "linkedin": {
      "command": "bunx",
      "args": ["linkedin-mcp-server-ts"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

---

5. Streamable HTTP Mode

Expose the server over HTTP for remote agents or container setups:

bun run src/index.ts --transport streamable-http --host 127.0.0.1 --port 8000

• MCP Route: http://127.0.0.1:8000/mcp
• Healthcheck: http://127.0.0.1:8000/health

---

Authentication & Session Management

The server uses a persistent browser profile at ~/.linkedin-mcp/profile to preserve cookies between runs.

Option A: Auto-Import from Local Browser (Fastest)

If you are already logged in to LinkedIn on Chrome, Brave, Edge, Arc, or Vivaldi, import the cookies directly:

# Auto-detect the most recent browser session
bunx linkedin-mcp-server-ts --import-from-browser

# Target a specific browser
bunx linkedin-mcp-server-ts --import-from-browser brave
bunx linkedin-mcp-server-ts --import-from-browser chrome
bunx linkedin-mcp-server-ts --import-from-browser edge

Option B: Interactive Visual Login

Open an interactive browser window to log in:

bunx linkedin-mcp-server-ts --login
# Or from local source:
bun run login

1. Chrome opens the LinkedIn login page.
2. Complete login (including 2FA or security challenges if prompted).
3. Once the feed loads, the server saves the session cookies and exits.

Check Session Status

bunx linkedin-mcp-server-ts --status
# Or from local source:
bun run status

Logout & Clear Session

bunx linkedin-mcp-server-ts --logout
# Or from local source:
bun run logout

---

Configuration & Environment Variables

Configure settings via CLI flags or a .env file in the workspace root:

Variable	CLI Flag	Default	Description
USER_DATA_DIR	--user-data-dir	~/.linkedin-mcp/profile	Path to persistent browser profile directory
HEADLESS	--headless / --no-headless	true	Run browser in headless mode
TRANSPORT	--transport	stdio	Transport protocol: stdio or streamable-http
HOST	--host	127.0.0.1	HTTP bind host
PORT	--port	8000	HTTP port
HTTP_PATH	--path	/mcp	HTTP endpoint path
TIMEOUT	--timeout	5000	DOM navigation/interaction timeout (ms)
TOOL_TIMEOUT	--tool-timeout	180	Per-tool MCP execution timeout (seconds)
LOGIN_TIMEOUT	--login-timeout	1800	Maximum wait time during --login (seconds)
LOGIN_INLINE_WAIT	--login-inline-wait	25	Wait time for inline authentication fallback (seconds)
AUTO_IMPORT_FROM_BROWSER	--auto-import / --no-auto-import	true	Automatically import cookies if no profile exists
CHROME_PATH	--chrome-path	"" (auto-detected)	Path to Chrome/Chromium executable binary
USER_AGENT	--user-agent	""	Custom User-Agent string override
VIEWPORT	--viewport	1280x720	Browser viewport dimensions (WIDTHxHEIGHT)
DEBUG_PORT	--debug-port	9222	Chrome remote debugging port used during --login
LOG_LEVEL	--log-level	WARNING	Logging level (DEBUG, INFO, WARNING, ERROR)

---

Development, Testing & Code Quality

Running Tests

Execute the full suite of unit, integration, and contract tests:

# Run all tests in parallel
bun test --parallel

# Run specific test suites
bun run test:unit
bun run test:integration
bun run test:e2e
bun run test:coverage

Linting & Formatting

Code formatting and style rules follow Biome and the repository's TypeScript Style Guide:

# Check for lint issues and style violations
bun run lint

# Automatically apply safe fixes
bun run lint:fix

# Format files
bun run format

Generating Documentation

Generate and preview the TypeDoc API documentation:

# Build static documentation to ./docs
bun run docs

# Serve documentation locally
bun run docs:serve

Project Structure

linkedin-mcp-server-ts/
├── src/
│   ├── index.ts               # CLI entrypoint & transport routing (stdio / HTTP)
│   ├── config.ts              # CLI arguments & environment configuration
│   ├── browser/
│   │   ├── auth.ts            # Login, logout, status, and browser cookie importer
│   │   ├── cdp.ts             # Direct Chrome DevTools Protocol communication
│   │   ├── chrome-launch.ts   # Process launcher for visual login & remote attach
│   │   ├── manager.ts         # Bun.WebView & CDP lifecycle manager
│   │   └── types.ts           # Browser status types
│   ├── errors/                # Unified error handling & error hierarchy
│   ├── mcp/
│   │   └── create-server.ts   # MCP server registration & tool mounting
│   ├── middleware/            # Serialization queue for concurrent requests
│   ├── scraping/              # DOM extraction, text cleanup, link classifiers & URNs
│   ├── session/               # Cookie storage, profile directory, and persistence
│   ├── tools/                 # 19 MCP tool implementations
│   └── utils/                 # General text and DOM helpers
├── tests/                     # Unit, integration, and E2E test suites
├── .agents/                   # Coding standards, style rules, and agent skills
├── bunfig.toml                # Bun configuration & package registry settings
└── package.json               # Package metadata, dependencies, and scripts

---

Publishing

Publishing to npm is handled directly with Bun:

# Verify linting and tests pass
bun run lint
bun test --parallel

# Publish package
bun publish

---

Contributing

Contributions and pull requests are welcome.

1. Fork the repository: https://github.com/joaovjo/linkedin-mcp-server-ts
2. Create a feature branch following the Conventional Branch spec: git checkout -b feature/your-feature-name
3. Commit your changes following Conventional Commits: git commit -m 'feat: add specific feature'
4. Ensure all tests and lint checks pass: bun test --parallel && bun run lint
5. Push to your branch: git push origin feature/your-feature-name
6. Open a Pull Request.

---

License & Credits

• License: Distributed under the MIT License.
• Credits: Based on the architecture and scraper logic of stickerdaniel/linkedin-mcp-server by Daniel Sticker and contributors.