Loxo MCP Server

Loxo MCP 服务

📚 文档： https://tbensonwest.github.io/loxo-mcp-server/

一个模型上下文协议（MCP）服务，可让 Claude 直接访问 Loxo 招聘平台。1.7.0 版提供 34 个工具，涵盖招聘人员的完整工作流：搜索和调查候选人、管理职位流程、跟踪活动和沟通、处理公司事务，以及维护候选人记录。工具描述会引导 Claude 展示招聘人员的初步沟通记录和包含丰富情报信息的活动历史，因此它无需你费力查找，就能回答“我们和这位候选人谈到哪一步了？”

安装

选项 0：通过 Smithery 安装（最简单）

通过 Smithery 自动为 Claude Desktop 安装：

npx -y @smithery/cli install loxo-mcp-server --client claude

选项 1：本地安装

# Clone the repository
git clone [repository-url]
cd loxo-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

选项 2：Docker 安装

# Clone the repository
git clone [repository-url]
cd loxo-mcp-server

# Build the Docker image
docker build -t loxo-mcp-server .

# Or use Docker Compose
docker-compose build

配置

将提供的 .env.example 文件复制为 .env，并填写相应值：

cp .env.example .env

然后更新 .env 文件以完成配置：

LOXO_API_KEY=your_api_key
LOXO_DOMAIN=app.loxo.co
LOXO_AGENCY_SLUG=your_agency_slug

必需的环境变量：

• LOXO_API_KEY：你的 Loxo API 密钥
• LOXO_AGENCY_SLUG：你在 Loxo 中的机构 slug
• LOXO_DOMAIN：（可选）默认为 'app.loxo.co'
• LOXO_DEFAULT_OWNER_ID：（可选）默认的 Loxo 用户 ID，用作通过此服务创建或更新的候选人的 owned_by_id。可通过 loxo_list_users 查找你的 ID。如果未设置，则不指定负责人；每次调用时可通过 owned_by_id 参数覆盖。
• LOXO_DEFAULT_OWNER_EMAIL：（可选）交易负责人的默认邮箱。如果未提供 owner_email 参数，则由 loxo_create_deal 使用。可通过 loxo_list_users 查找邮箱。

Docker 配置

使用 Docker 时，环境变量会通过 Docker Compose 自动从 .env 文件加载，也可以直接传入：

使用 Docker Compose（推荐）：

# Ensure your .env file is configured
docker-compose up

直接使用 Docker：

docker run -i \
  -e LOXO_API_KEY=your_api_key \
  -e LOXO_AGENCY_SLUG=your_agency_slug \
  -e LOXO_DOMAIN=app.loxo.co \
  loxo-mcp-server

注意：必须使用 -i 标志，因为 MCP 服务通过 stdin/stdout 通信。

使用

运行服务

本地运行：

npm start

使用 Docker Compose：

docker-compose up

直接使用 Docker：

docker run -i \
  -e LOXO_API_KEY=your_api_key \
  -e LOXO_AGENCY_SLUG=your_agency_slug \
  loxo-mcp-server

与 Claude Desktop 集成

将以下内容添加到 Claude Desktop 配置文件（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

本地安装：

{
  "mcpServers": {
    "loxo": {
      "command": "node",
      "args": ["/path/to/loxo-mcp-server/build/index.js"],
      "env": {
        "LOXO_API_KEY": "your_api_key",
        "LOXO_AGENCY_SLUG": "your_agency_slug",
        "LOXO_DOMAIN": "app.loxo.co"
      }
    }
  }
}

Docker 安装：

{
  "mcpServers": {
    "loxo": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "LOXO_API_KEY=your_api_key",
        "-e", "LOXO_AGENCY_SLUG=your_agency_slug",
        "-e", "LOXO_DOMAIN=app.loxo.co",
        "loxo-mcp-server"
      ]
    }
  }
}

工作流示例

准备客户简报资料包

“为 Northvale 职位准备一份简报资料包。”

1. loxo_search_jobs — 查找 Northvale 职位并获取其 ID
2. loxo_get_job_pipeline — 获取所有候选人及其当前阶段
3. loxo_get_candidate_brief（针对每位候选人）— 一次调用即可获取初步沟通记录、联系方式和近期的丰富情报活动
4. 汇总成结构化简报文档，包含当前阶段、求职动机、薪酬预期和近期联系记录

---

职位流程状态更新

“告诉我所有活跃候选人的最新状态。”

1. loxo_get_job_pipeline — 获取该职位的所有候选人及其阶段
2. loxo_get_candidate_brief（针对每位候选人）— 获取初步沟通记录和近期活动，以总结每段沟通的进展
3. 提供简洁的状态摘要：阶段、最近联系时间、下一步

---

为新职位匹配候选人

“我们的数据库中，谁适合这个新的 CFO 职位？”

1. loxo_search_candidates — 使用 Lucene 查询，按职位、技能、行业和标签搜索
2. loxo_get_candidate_brief（适用于已入围的候选人）— 查看接洽记录和活动历史，评估候选人是否真正合适以及目前是否有求职意向
3. 根据招聘顾问的备注和近期对话中的佐证信息，列出最匹配的人选

可用工具

查找和研究候选人

• loxo_search_candidates — 使用 Lucene 查询搜索候选人数据库。可按当前职位、过往雇主、技能、标签、地点或任意组合进行筛选。每页返回 100 条结果，包含技能集和标签，因此无需额外调用即可进行筛选。对已入围的候选人，可接着调用 loxo_get_candidate_brief。
• loxo_get_candidate — 完整的候选人档案，包含个人简介、当前职位、技能、标签、薪酬，以及招聘顾问的接洽记录和通话备注（位于 description 字段）。description 字段通常是候选人信息最丰富的来源：包括求职动机、个人情况、薪酬期望和职位偏好。
• loxo_get_candidate_brief — 需要了解候选人完整背景时的首选工具。一次调用即可返回档案（包括接洽记录）、所有联系方式，以及近期包含丰富信息的活动（通话、邮件、备注、面试，并已过滤掉流程噪声）。在起草联系内容、准备候选人简介材料或评估候选人与职位的匹配度之前，请使用此工具。支持通过 scroll_id 分页，以查阅更早的活动记录。
• loxo_get_person_emails — 候选人留存的所有电子邮件地址，以及类型标签（工作、个人等）。
• loxo_get_person_phones — 候选人留存的所有电话号码，以及类型标签（手机、工作、家庭等）。
• loxo_list_person_job_profiles — 候选人的完整工作经历列表：所有职位、公司和任职日期。
• loxo_get_person_job_profile_detail — 候选人工作经历中特定职位的详细信息。需要查看某个职位的完整描述时，请在调用 loxo_list_person_job_profiles 后使用此工具。
• loxo_list_person_education_profiles — 候选人的完整教育经历：所有学位、学校和就读日期。
• loxo_get_person_education_profile_detail — 特定教育经历的详细信息。需要查看某项学历的完整详情时，请在调用 loxo_list_person_education_profiles 后使用此工具。

管理招聘流程和职位

• loxo_search_jobs — 使用 Lucene 查询搜索开放职位（标题、地点或任意组合）。使用基于页码的分页。
• loxo_get_job — 完整的职位详情，包含职位描述、要求、薪酬、状态和招聘团队。
• loxo_get_job_pipeline — 查看目前处于某职位招聘流程中的所有候选人及其流程阶段（寻访、筛选、面试、录用、入职）。返回候选人 ID 和阶段；要查看每位候选人的完整背景，请接着调用 loxo_get_candidate_brief。
• loxo_add_to_pipeline — 将候选人添加到某职位的招聘流程中。候选人会进入第一阶段，并显示在 loxo_get_job_pipeline 中。

交易与业务拓展管道

• loxo_list_deal_workflows — 列出所有交易工作流（管道）及其 ID 和名称。可用于在搜索或创建交易前了解现有哪些管道。
• loxo_get_deal_workflow — 获取交易工作流的详细信息，包括管道阶段。可用于查找 loxo_create_deal 的有效 pipeline_stage_id 值。
• loxo_search_deals — 使用可选的 Lucene 查询和负责人邮箱筛选条件搜索交易。使用基于游标的分页，并通过 scroll_id 追踪。
• loxo_get_deal — 获取完整的交易详情，包括名称、金额、成交日期、管道阶段，以及关联的公司、人员和职位。
• loxo_create_deal — 在管道中创建新交易。需要提供名称、金额、成交日期、工作流 ID 和管道阶段 ID。若未指定负责人邮箱，则使用 LOXO_DEFAULT_OWNER_EMAIL。
• loxo_log_deal_activity — 在交易中记录活动。使用该交易的 workflow_id 调用 loxo_get_activity_types，查找交易专用的活动类型 ID。

跟踪活动与沟通

• loxo_get_candidate_activities — 获取候选人的完整活动时间线：所有电话、电子邮件、会议、备注、管道变更和自动化事件，按时间从近到远排列。可选使用 activity_type_ids 筛选（调用 loxo_get_activity_types 查找 ID）。如需更简洁、侧重关键信息的视图，请改用 loxo_get_candidate_brief。
• loxo_log_activity — 记录候选人已完成的活动（电话、电子邮件、会议、面试）。先调用 loxo_get_activity_types 查找正确的活动类型 ID。
• loxo_schedule_activity — 为候选人创建未来活动（电话、会议、面试）。先调用 loxo_get_activity_types 查找正确的活动类型 ID。
• loxo_get_todays_tasks — 获取今天（或指定日期范围内）的所有已安排事项。可选按用户筛选。
• loxo_get_activity_types — 列出所有活动类型及其 ID。可选传入 workflow_id，以获取交易专用的活动类型，而非候选人活动类型。记录或安排活动前请调用此工具。

公司与参考数据

• loxo_create_company — 创建新公司（客户／目标客户）。目前仅接受 name。
• loxo_search_companies — 使用 Lucene 查询搜索公司数据库。使用基于游标的分页，并通过 scroll_id 追踪。
• loxo_get_company_details — 获取完整的公司档案，包括描述、联系人、关系和状态。
• loxo_list_users — 列出 Loxo 机构中的所有用户（招聘人员、协调员等）及其姓名和电子邮件地址。可用于查找 user_id 值，以筛选任务或检查记录归属。
• loxo_list_skillsets — 列出所有技能组和行业经验选项及其 ID。调用 loxo_update_candidate 前，可用于查找有效的 skillset_ids 和 sector_ids 值。
• loxo_list_source_types — 列出所有候选人来源类型（LinkedIn、API、推荐等）及其 ID。可用于查找有效的 source_type_id 值。
• loxo_list_person_types — 列出所有人员类型类别（在职候选人、潜在候选人等）及其 ID。可用于查找有效的 person_type_id 值。

候选人管理

• loxo_create_candidate — 创建新的候选人记录，包含姓名、联系信息和当前职位。创建后，使用 loxo_update_candidate 设置标签、技能组、人员类型和来源类型。
• loxo_update_candidate — 更新现有候选人的详细信息：档案字段、标签、技能组、行业、人员类型和来源类型。请先使用 loxo_list_skillsets 和 loxo_list_person_types 查找有效 ID。
• loxo_upload_resume — 将 CV 或简历文件上传到候选人档案。接受 Base64 编码的文件内容。文件会显示在其 Loxo 记录的简历部分。

架构

基于 Model Context Protocol SDK 构建，通过 stdio 通信，可与 Claude Desktop 和 Claude.ai 无缝集成。

• v1.7.0 — 34 个工具；工具描述会引导 Claude 提取招聘人员的需求记录（description 字段）和包含丰富情报的活动（电话、电子邮件、备注、面试），同时过滤掉流水线自动化噪声
• 所有 API 调用均发送至 https://{LOXO_DOMAIN}/api/{LOXO_AGENCY_SLUG}/...，并使用 Bearer 令牌进行身份验证
• POST/PATCH 请求正文使用 application/x-www-form-urlencoded，并采用方括号表示法（例如 person[name]）
• 所有端点均已根据 Loxo 官方 OpenAPI 规范验证

分页

根据端点不同，采用两种分页方式：

• 基于游标（scroll_id） — 用于候选人、公司、交易、日程项目和活动。将响应中的 scroll_id 传递到下一次请求，以遍历各页。
• 基于页码（page / per_page） — 用于职位。传递 page=1、page=2 等参数。

活动与事件系统

所有活动跟踪（电话、电子邮件、会议、备注、流水线变更）均通过 person_events API 进行：

• 已安排的活动 — 使用 loxo_schedule_activity，并设置未来的 created_at 日期时间
• 已完成的活动 — 使用 loxo_log_activity；系统会自动应用当前时间戳
• 活动可以关联个人、职位和／或公司
• loxo_get_candidate_brief 仅筛选包含丰富情报的活动类型（排除流水线自动化事件和其他低信号条目）

开发

本地开发

# Run in development mode with watch mode
npm run dev

# Build the project
npm run build

# Start the server
npm start

Docker 开发

# Rebuild after code changes
docker-compose build

# Run with live logs
docker-compose up

# Run in detached mode
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the container
docker-compose down