PeopleBox

You set up the PeopleBox ATS MCP server to enable Claude Desktop or any MCP-compatible LLM client to access ATS data. This server exposes tools and resources that let you search and manage candidates, positions, pipelines, and lookup data through the MCP interface, making it easy to integrate ATS insights into your conversational workflows.

How to use

You connect an MCP client to the PeopleBox ATS MCP server by choosing either the HTTP or STDIO mode, then using the available tools to query candidates, explore positions, or review pipeline data. In STDIO mode, you run a local CLI that communicates with the server through standard input and output. In HTTP mode, you start a local HTTP endpoint that the MCP client can call to perform operations. Use your client to search for candidates, get full candidate profiles, create candidates, inspect positions, and fetch related statistics or timeline data. You can also retrieve source and lookup resources such as sources, skills, companies, and schools to enrich your searches and results.

How to install

Prerequisites you need to prepare before installing:

• Node.js v18+

• Git

Step by step install and run commands:

# 1. Clone the repository
git clone https://github.com/melihguven98/peoplebox-mcp.git

# 2. Change into the project directory
cd peoplebox-mcp

# 3. Install dependencies
npm install

# 4. Build the project
npm run build

Additional sections

Configuration notes, run modes, and troubleshooting help are provided to help you operate the PeopleBox ATS MCP server smoothly. You can run in STDIO mode for local testing or HTTP mode for a network-accessible MCP endpoint. The server relies on a set of environment variables that you pass to the client or runtime to configure API access and ports.

Configuration and run modes

The server uses a small set of environment variables to control API access and how it operates. You can set these variables in your MCP client configuration or when launching the server in STDIO or HTTP mode.

Environment variables shown in the examples include the base API URL, login credentials for the MCP API, and an optional port for HTTP mode. You can customize paths to the CLI entry when using STDIO mode.

{
  "mcpServers": {
    "PeopleBox": {
      "command": "node",
      "args": ["dist/cli.js"],
      "env": {
        "API_BASE_URL": "https://api.peoplebox.com/api/v1",
        "MCP_API_EMAIL": "recruiter@peoplebox.com",
        "MCP_API_PASSWORD": "sifre123"
      }
    }
  }
}

Troubleshooting

If you encounter login or connection issues, verify that you provided the correct API credentials and API base URL. Common problems include a 401 login failure or an ECONNREFUSED when the API base URL is incorrect or the API service is not running. Ensure the configuration paths and JSON syntax are correct for the client you are using, and restart the MCP client if needed.

Tools and resources overview

The server exposes a set of tools and resources that enable comprehensive ATS data interactions. You can search and retrieve candidate data, inspect positions, fetch pipeline-related information, and access lookup data such as sources, skills, companies, schools, and position statistics.

Server connection methods and configuration samples

Two MCP connection methods are available: a local STDIO server and a local HTTP server. The STDIO mode runs a local CLI, while the HTTP mode exposes an HTTP endpoint that MCP clients can call.

Available tools

search_candidates

Search candidates by name, email, phone, or keyword.

get_candidate

Retrieve a full candidate profile including skills, education, and experience.

create_candidate

Create a new candidate profile in the ATS.

add_candidate_note

Add a note to a candidate profile.

check_candidate_email

Validate or look up a candidate by email.

search_positions

Search for job positions by criteria.

get_position

Get detailed information about a position.

get_position_statistics

Fetch general statistics for positions.

get_candidate_positions

List positions associated with a candidate.

get_candidate_timeline

Fetch a candidate's activity timeline.

sources

Retrieve candidate sources.

skills

Retrieve the skills lookup.

companies

Retrieve the companies lookup.

schools

Retrieve the schools lookup.

position_statistics

Retrieve position statistics.