linkedin-mcp-server-ts

v0.2.0

Published

a month ago

High-performance TypeScript & Bun MCP server for LinkedIn scraping and automation

Downloads

0High
0Medium
0Low

joaovjo

mcp linkedin scraping model-context-protocol bun typescript

LinkedIn MCP Server (TypeScript / Bun)

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

Available MCP Tools (19 Tools)

Quickstart

Prerequisites

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

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

Chrome opens the LinkedIn login page.
Complete login (including 2FA or security challenges if prompted).
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:

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.

Fork the repository: https://github.com/joaovjo/linkedin-mcp-server-ts
Create a feature branch following the Conventional Branch spec: git checkout -b feature/your-feature-name
Commit your changes following Conventional Commits: git commit -m 'feat: add specific feature'
Ensure all tests and lint checks pass: bun test --parallel && bun run lint
Push to your branch: git push origin feature/your-feature-name
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.