How do I use PeopleBox ATS MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@PeopleBox ATS MCP Server find the profile for Alice Johnson and show her recent activity" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

PeopleBox ATS — MCP Server

PeopleBox ATS için MCP (Model Context Protocol) server. Claude Desktop veya herhangi bir MCP uyumlu LLM client'ın ATS verilerine erişmesini sağlar.

Kurulum

Gereksinimler

Node.js v18+
Git

Adımlar

# 1. Repo'yu klonla
git clone https://github.com/melihguven98/peoplebox-mcp.git

# 2. Bağımlılıkları kur
cd peoplebox-mcp
npm install

# 3. Derle
npm run build

Claude Desktop Yapılandırması

Config dosyasını aç:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Aşağıdaki JSON'u yapıştır (args içindeki yolu kendi bilgisayarına göre düzelt):

Windows

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

macOS / Linux

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

Önemli: KULLANICI kısmını kendi kullanıcı adınla değiştir.

Claude Desktop'u yeniden başlat. Sol altta MCP tool ikonu görünecek.

Yapılandırma

Değişken	Varsayılan	Açıklama
`API_BASE_URL`	`http://localhost:3001/api/v1`	PeopleBox API adresi
`MCP_API_EMAIL`	`recruiter@peoplebox.com`	API login email
`MCP_API_PASSWORD`	`password123`	API login şifresi
`MCP_PORT`	`3002`	HTTP modu port (sadece `npm start` için)

Çalıştırma Modları

Stdio Modu (Claude Desktop — önerilen)

Claude Desktop bu modu otomatik kullanır. Manuel test için:

API_BASE_URL=https://api.peoplebox.com/api/v1 node dist/cli.js

HTTP Modu (MCP Inspector, Claude Code, vs.)

API_BASE_URL=https://api.peoplebox.com/api/v1 npm start
# → http://localhost:3002/mcp

Mevcut Tool'lar (10 adet)

Aday (Candidate)

Tool	Açıklama
`search_candidates`	Aday arama (isim, email, telefon, keyword)
`get_candidate`	Tam aday profili (skills, education, experience)
`create_candidate`	Yeni aday oluştur
`add_candidate_note`	Adaya not ekle
`check_candidate_email`	Email ile aday kontrol

Pozisyon (Position)

Tool	Açıklama
`search_positions`	Pozisyon arama
`get_position`	Pozisyon detayı
`get_position_statistics`	Genel pozisyon istatistikleri

Pipeline

Tool	Açıklama
`get_candidate_positions`	Adayın bulunduğu pozisyonlar
`get_candidate_timeline`	Aday aktivite geçmişi

Mevcut Resource'lar (5 adet)

Resource	URI	Açıklama
`sources`	`ats://lookups/sources`	Aday kaynakları
`skills`	`ats://lookups/skills`	Yetenek listesi
`companies`	`ats://lookups/companies`	Şirket listesi
`schools`	`ats://lookups/schools`	Okul listesi
`position_statistics`	`ats://positions/statistics`	Pozisyon istatistikleri

Test (MCP Inspector)

npx @modelcontextprotocol/inspector

Tarayıcıda http://localhost:6274 adresine git
Transport type: STDIO
Command: node
Args: dist/cli.js
Environment: API_BASE_URL=https://api.peoplebox.com/api/v1
Connect butonuna tıkla

Dosya Yapısı

peoplebox-mcp/
├── package.json
├── tsconfig.json
└── src/
    ├── index.ts              # HTTP server (Express + Streamable HTTP)
    ├── cli.ts                # Stdio CLI (Claude Desktop bu dosyayı çalıştırır)
    ├── config.ts             # Environment değişkenleri
    ├── api-client.ts         # API HTTP client (cookie auth, auto re-login)
    ├── tools/
    │   ├── index.ts          # Tool barrel
    │   ├── candidates.ts     # Aday tool'ları (5 tool)
    │   ├── positions.ts      # Pozisyon tool'ları (3 tool)
    │   └── pipeline.ts       # Pipeline tool'ları (2 tool)
    └── resources/
        ├── index.ts          # Resource barrel
        └── lookups.ts        # Lookup resource'ları (5 resource)

Sorun Giderme

Sorun	Çözüm
`Login failed (401)`	`MCP_API_EMAIL` / `MCP_API_PASSWORD` doğru mu?
`ECONNREFUSED`	`API_BASE_URL` doğru mu? API çalışıyor mu?
Claude Desktop tool ikonu yok	Config dosya yolu ve JSON syntax'ı doğru mu? Claude Desktop'u yeniden başlattın mı?
Windows'ta `ENOENT` hatası	`args` içindeki yolda `\\` (double backslash) kullandığından emin ol

PeopleBox ATS MCP Server