LinkedIn MCP 服务

本项目实现了一个模型上下文协议（MCP）服务器，使用 Playwright 自动化 LinkedIn 招聘流程中的关键功能。它提供以下工具：

• 检查和执行 LinkedIn 登录（支持可选的验证码提交）
• 应用人员搜索过滤器
• 获取分页的人员搜索结果
• 获取任何 LinkedIn 成员的个人资料详情

⚠️ 请负责任地使用此集成。遵守 LinkedIn 的服务条款和速率限制；缓存并重用会话，而不是每次调用都重新登录。

快速开始

1. 安装依赖（Playwright 会自动下载 Chromium）：

   pnpm install
   pnpm exec playwright install chromium

1. 复制 .env.example 到 .env（或 .env.local）并设置凭据：

   cp .env.example .env.local

1. 以监视模式运行 MCP 服务器：

   pnpm dev

环境变量：

• LINKEDIN_EMAIL / LINKEDIN_PASSWORD – 当 MCP 客户端未提供凭据时的可选默认值
• PLAYWRIGHT_HEADLESS – 设置为 false 可观察浏览器运行
• PLAYWRIGHT_USER_DATA_DIR – 持久化 Chromium 配置文件的自定义路径

可用工具

• linkedin.login – 检查或执行登录。输入支持 email、password、verificationCode 和可选的 sessionKey（用于管理多个用户存储）
• linkedin.search.applyFilters – 应用过滤器并返回生成的搜索 URL，不抓取结果
• linkedin.search.people – 返回搜索结果元数据，支持分页（filters.page）
• linkedin.profile.details – 抓取成员个人资料（工作经历、教育背景、技能、简介）

所有工具都接受 verificationCode 来完成检查点挑战，并返回结构化的 JSON（或描述下一步操作的错误信息）。

使用说明

1. 配置 MCP 客户端

在 Claude Desktop 或其他 MCP 客户端中配置此服务器。编辑配置文件（例如 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "linkedin": {
      "command": "node",
      "args": ["/path/to/linkedin-mcp/dist/index.js"],
      "env": {
        "LINKEDIN_EMAIL": "[email protected]",
        "LINKEDIN_PASSWORD": "your-password",
        "PLAYWRIGHT_HEADLESS": "true"
      }
    }
  }
}

2. 基本使用流程

#### 第一步：登录 LinkedIn

{
  "tool": "linkedin.login",
  "arguments": {
    "email": "[email protected]",
    "password": "your-password"
  }
}

成功响应：

{
  "service": "linkedin.login",
  "headless": true,
  "result": {
    "status": "success",
    "message": "已成功登录 LinkedIn"
  }
}

需要验证码时的响应：

{
  "service": "linkedin.login",
  "error": "需要验证码",
  "loginResult": {
    "status": "challenge",
    "challengeUrl": "https://www.linkedin.com/checkpoint/challenge/...",
    "message": "LinkedIn 要求验证。请提供验证码。"
  }
}

提交验证码：

{
  "tool": "linkedin.login",
  "arguments": {
    "email": "[email protected]",
    "password": "your-password",
    "verificationCode": "123456"
  }
}

#### 第二步：搜索人员

应用搜索过滤器（仅获取 URL）：

{
  "tool": "linkedin.search.applyFilters",
  "arguments": {
    "email": "[email protected]",
    "filters": {
      "keywords": "软件工程师",
      "locations": ["中国", "北京"],
      "currentCompanies": ["腾讯", "阿里巴巴"],
      "industries": ["互联网"]
    }
  }
}

响应：

{
  "service": "linkedin.search.applyFilters",
  "searchUrl": "https://www.linkedin.com/search/results/people/?keywords=...",
  "loginResult": {
    "status": "already_logged_in"
  }
}

获取搜索结果（带分页）：

{
  "tool": "linkedin.search.people",
  "arguments": {
    "email": "[email protected]",
    "filters": {
      "keywords": "产品经理",
      "locations": ["上海"],
      "page": 1
    }
  }
}

响应：

{
  "service": "linkedin.search.people",
  "results": [
    {
      "name": "张三",
      "headline": "高级产品经理 @ 某科技公司",
      "location": "上海",
      "profileUrl": "https://www.linkedin.com/in/zhangsan"
    }
  ],
  "totalResults": 150,
  "currentPage": 1,
  "loginResult": {
    "status": "already_logged_in"
  }
}

#### 第三步：获取个人资料详情

{
  "tool": "linkedin.profile.details",
  "arguments": {
    "email": "[email protected]",
    "profileUrl": "https://www.linkedin.com/in/zhangsan"
  }
}

响应：

{
  "service": "linkedin.profile.details",
  "profile": {
    "name": "张三",
    "headline": "高级产品经理",
    "summary": "拥有 8 年产品经验...",
    "location": "上海",
    "experiences": [
      {
        "title": "高级产品经理",
        "company": "某科技公司",
        "duration": "2020 - 至今",
        "description": "负责产品规划和设计..."
      }
    ],
    "education": [
      {
        "school": "清华大学",
        "degree": "计算机科学学士",
        "years": "2010 - 2014"
      }
    ],
    "skills": ["产品管理", "用户体验设计", "数据分析"]
  }
}

3. 高级功能

#### 使用 sessionKey 管理多个账户

{
  "tool": "linkedin.login",
  "arguments": {
    "email": "[email protected]",
    "password": "password1",
    "sessionKey": "recruiter-account-1"
  }
}

不同的 sessionKey 将创建独立的浏览器会话，允许同时管理多个 LinkedIn 账户。

#### 使用低级查询参数

对于高级搜索需求，可以直接传递 LinkedIn 的原始查询参数：

{
  "tool": "linkedin.search.people",
  "arguments": {
    "email": "[email protected]",
    "filters": {
      "queryParams": {
        "geoUrn": "103644278",
        "network": ["F", "S"],
        "resultType": "PEOPLE"
      }
    }
  }
}

4. 错误处理

所有工具调用都可能返回以下错误状态：

• 认证错误：需要重新登录或提供验证码
• 网络错误：LinkedIn 服务不可用
• 速率限制：请求过于频繁，需要等待
• 无效参数：输入参数格式错误

错误响应示例：

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "{\"service\":\"linkedin.search.people\",\"error\":\"认证失败，请重新登录\"}"
    }
  ]
}

5. 最佳实践

1. 会话复用：登录后，浏览器会话会被缓存。后续调用无需重复登录。
2. 尊重速率限制：避免短时间内发送大量请求，建议在请求之间添加延迟。
3. 错误重试：遇到临时错误时，等待几秒后重试。
4. 验证码处理：当收到 status: "challenge" 响应时，及时处理验证码。
5. 数据缓存：对于不经常变化的数据（如个人资料），建议在应用层进行缓存。

开发说明

• 浏览器会话使用 Playwright 持久化配置文件按 sessionKey 缓存
• SearchService 允许使用底层的 filters.queryParams 来转发原始 LinkedIn 查询参数，当你已经知道精确的 URN 时（例如 geoUrn 或 network facets）
• 当 LinkedIn 提示检查点验证时，工具会返回 status: "challenge" 以及 challengeUrl；从用户那里收集验证码并使用 verificationCode 重新运行

测试

当前测试套件是一个占位符。你可以通过指向受控的 LinkedIn 沙盒账户来添加集成冒烟测试（使用模拟凭据）：

pnpm test

对于生产环境，在没有明确合规审查的情况下，避免针对真实个人资料运行自动化测试。