boss-cli-mcp

An automation CLI and MCP service for Boss 直聘, extended from joohw/boss-cli.

The project drives the local Chrome via Puppeteer/CDP, reuses the local login state, and provides MCP-capable AI clients such as Claude Desktop, Cursor, and Zcode with candidate lookup, chat, message sending, batch replies, recommended search, and position management capabilities.

This project performs real operations on your Boss account. Before sending messages, getting intros, viewing resumes, or running deep matching, please confirm the candidate and parameters, and follow the platform rules.

Features

• Read the full or unread candidate list

• Open a chat by name or by list index

• Send a single message

• Reply to candidates in batches asynchronously

• Query batch send progress and per-person results

• Chat actions such as requesting a resume, adding a remark, marking "not suitable", and swapping WeChat

• Read recommended candidates and regular search results

• Deep search and match

• Preview online resumes

• Read a position list or position details

• Invoke via both CLI and stdio MCP

Related MCP server: Chrome MCP Server

Environment Requirements

• Node.js 20 or higher

• Chrome or Chromium installed on your machine

• Windows, macOS, or Linux

• An account that can log in to the Boss 直聘 employer portal

Installation

Run MCP from this repository

git clone https://github.com/bmbbms/boss-cli-mcp.git D:\boss-cli
cd D:\boss-cli
npm install
npm run build

The built MCP entry point:

D:\boss-cli\dist\mcp\index.js

To start a manual test:

& "D:\nodejs\node.exe" "D:\boss-cli\dist\mcp\index.js"

MCP uses stdio communication. After startup, having no normal output in the terminal is expected. Press Ctrl+C to stop the test process.

Install the upstream CLI

If you only need the CLI, you can install the upstream npm package directly:

npm install -g @joohw/boss-cli@latest
boss help

Configure MCP clients

Zcode

{
  "boss-recruiter": {
    "type": "stdio",
    "command": "D:\\nodejs\\node.exe",
    "args": [
      "D:\\boss-cli\\dist\\mcp\\index.js"
    ]
  }
}

Claude Desktop

Add the following to the Claude Desktop MCP config file:

{
  "mcpServers": {
    "boss-recruiter": {
      "command": "D:\\nodejs\\node.exe",
      "args": [
        "D:\\boss-cli\\dist\\mcp\\index.js"
      ]
    }
  }
}

Notes:

• command should contain only the path to the Node.js executable.

• The full MCP file path must be a single string in args; it cannot be split on spaces.

• Backslashes in JSON on Windows must be written as \\.

• After changing the config, fully restart or reload the MCP client.

If you are unsure about the Node.js install path, run this in PowerShell:

(Get-Command node).Source

First login

After the MCP client connects successfully, call:

boss_login

The tool opens your local Chrome. After scanning the QR code or completing verification, later operations reuse the local browser session stored in ~/.boss-cli/.

MCP tools

Batch send messages

Recommended workflow

1. Call boss_list_candidates to get the candidate list first.

2. Show the list to the user and have them confirm it.

3. Call boss_batch_send_messages to start the batch send task.

4. Save the returned taskId.

5. Call boss_batch_send_status to fetch the progress until the status becomes completed or failed.

Start a batch send

{
  "messages": [
    {
      "candidateName": "张三",
      "text": "您好，感谢您的关注，请问方便补充一下简历吗？",
      "exact": true
    },
    {
      "candidateName": "李四",
      "text": "您好，感谢您的关注，请问方便补充一下简历吗？",
      "exact": true
    }
  ],
  "confirm": true
}

It starts asynchronously by default and returns immediately:

{
  "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "running",
  "total": 2
}

Check the task status

Call boss_batch_send_status:

{
  "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

When complete, it returns something like:

{
  "status": "completed",
  "total": 2,
  "sent": 1,
  "failed": 1,
  "results": [
    {
      "candidateName": "张三",
      "status": "sent"
    },
    {
      "candidateName": "李四",
      "status": "failed",
      "error": "未找到候选人"
    }
  ]
}

Arguments:

• candidateName: the candidate name; preferably from the boss_list_candidates result.

• text: the message body to send.

• exact: whether to match the name exactly; keep true.

• confirm: must be explicitly true or nothing will be sent.

• waitForCompletion: defaults to false. Setting it to true is not recommended, because it may trigger an MCP client timeout while the page is loading for the first time.

The batch tool processes candidates serially and records a sent or failed status for each person. A failure for one candidate does not stop the others from being processed.

Example prompts in AI clients

调用 boss_list_candidates 获取未读候选人，将列表展示给我并等待确认。
我确认后，使用 boss_batch_send_messages 逐个发送指定消息。
必须精确匹配姓名并设置 confirm=true。
取得 taskId 后，定期调用 boss_batch_send_status，最后汇总成功和失败结果。

CLI quick use

# 登录
boss login

# 查看未读候选人
boss list --unread

# 打开聊天并发送消息
boss chat 张三 --strict
boss send --text "您好，请问方便发一下简历吗？"

# 查看推荐候选人
boss recommend 前端工程师

# 常规搜索
boss search "AI 产品经理"

Full CLI arguments:

boss help

FAQ

MCP reports Cannot find module at startup

This is usually caused by a path with spaces being split into multiple arguments. Make sure the full MCP path is a single string in the args array:

"args": ["D:\\boss-cli\\dist\\mcp\\index.js"]

First MCP call times out

The first call requires launching or connecting to Chrome and loading the Boss page, which can take a while. Batch sends use an async task by default, so save the taskId and query via boss_batch_send_status instead of starting the task again.

If a synchronous call appears to time out, the operation may still be running in the browser. Check the chat history before retrying the send to avoid duplicates.

After updating the source, the MCP tools are not refreshed

Rebuild and restart the MCP client:

cd D:\boss-cli
npm run build

Where is the data stored?

These files stay on your machine and should not be committed to GitHub.

Development

npm install
npm run build
npm run mcp

The main MCP implementation is located at:

• src/mcp/index.ts

• src/toolset/

• docs/mcp.md

Upstream and license

This repository is based on joohw/boss-cli and keeps the original GPL-3.0 license.

This project adds the MCP service, MCP client docs, batch sending, and async task status query support.

See LICENSE.