Skip to main content
Glama
@kula-ai/mcp-server

@kula-ai/mcp-server

Official
by kula-ai
README.md
# @kula-ai/mcp-server

[![CI](https://github.com/kula-ai/kula-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/kula-ai/kula-mcp-server/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/@kula-ai/mcp-server)](https://www.npmjs.com/package/@kula-ai/mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)

An MCP (Model Context Protocol) server for the [Kula](https://www.kula.ai) recruiting API. Connect AI assistants like Claude to your Kula account to list jobs, manage applications, configure webhooks, and more.

## Quick Start

### With Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "kula": {
      "command": "npx",
      "args": ["-y", "@kula-ai/mcp-server"],
      "env": {
        "KULA_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

<details>
<summary>With Cursor</summary>

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "kula": {
      "command": "npx",
      "args": ["-y", "@kula-ai/mcp-server"],
      "env": {
        "KULA_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

</details>

<details>
<summary>With Claude Code</summary>

```bash
claude mcp add kula -- npx -y @kula-ai/mcp-server
```

Then set `KULA_API_KEY` in your environment.

</details>

### Manual

```bash
npx @kula-ai/mcp-server
```

## Configuration

| Environment Variable | Required | Description |
|---------------------|----------|-------------|
| `KULA_API_KEY` | Yes | Your Kula API key |

Get your API key from [Kula Developer Settings](https://developers.kula.ai).

## Available Tools

51 tools across 13 categories:

<details>
<summary>Organization (4 tools)</summary>

| Tool | Description |
|------|-------------|
| `list_departments` | List all departments in the organization as a nested tree structure |
| `list_offices` | List all offices in the organization |
| `list_milestones` | List all hiring milestones (pipeline stage groupings) |
| `list_users` | List all active internal users (recruiters, hiring managers, coordinators) |

</details>

<details>
<summary>Sources (1 tool)</summary>

| Tool | Description |
|------|-------------|
| `list_sources` | List all candidate sources in the organization |

</details>

<details>
<summary>Rejection Reasons (1 tool)</summary>

| Tool | Description |
|------|-------------|
| `list_rejection_reasons` | List all rejection reasons configured in the organization |

</details>

<details>
<summary>Custom Fields (1 tool)</summary>

| Tool | Description |
|------|-------------|
| `list_custom_fields` | List custom fields by subject type. Required — valid values: `job`, `candidate`, `requisition`, `offer` |

</details>

<details>
<summary>Jobs (3 tools)</summary>

| Tool | Description |
|------|-------------|
| `list_jobs` | List jobs with filters (status, department, office, date ranges, sort) |
| `search_jobs` | Search jobs by title (partial match) with optional filters |
| `get_job` | Get details of a specific job |

</details>

<details>
<summary>Job Stages (3 tools)</summary>

| Tool | Description |
|------|-------------|
| `list_job_stages` | List all pipeline stages for a specific job |
| `create_job_stage` | Create a new pipeline stage for a job |
| `list_stage_activities` | List all activities configured for a specific job stage |

</details>

<details>
<summary>Job Posts (2 tools)</summary>

| Tool | Description |
|------|-------------|
| `list_job_posts` | List published job posts on the job board |
| `get_job_post` | Get details of a specific job post from the job board |

</details>

<details>
<summary>Candidates (5 tools)</summary>

| Tool | Description |
|------|-------------|
| `create_candidate` | Create a new candidate in the system |
| `list_candidates` | List candidates with simple filters (email, date ranges, sort) |
| `search_candidates` | Search candidates by name, email, skills, tags, location, and more |
| `get_candidate` | Get details of a specific candidate |
| `update_candidate` | Update an existing candidate's profile |

</details>

<details>
<summary>Applications (6 tools)</summary>

| Tool | Description |
|------|-------------|
| `list_applications` | List job applications |
| `get_application` | Get details of a specific application |
| `update_application_stage` | Update the stage of a specific application |
| `list_application_notes` | List notes on a specific application |
| `create_application_note` | Add a note to a specific application |
| `update_application_note` | Update an existing note on an application |

</details>

<details>
<summary>Scorecard Submissions (1 tool)</summary>

| Tool | Description |
|------|-------------|
| `list_scorecard_submissions` | List scorecard submissions for a specific application |

</details>

<details>
<summary>Webhooks (12 tools)</summary>

| Tool | Description |
|------|-------------|
| `list_webhooks` | List all configured webhooks |
| `create_webhook` | Create a new webhook subscription |
| `get_webhook` | Get details of a specific webhook |
| `update_webhook` | Update an existing webhook configuration |
| `delete_webhook` | Delete a webhook |
| `enable_webhook` | Enable a disabled webhook |
| `disable_webhook` | Disable an active webhook |
| `rotate_webhook_secret` | Rotate the signing secret for a webhook |
| `test_webhook` | Send a test payload to a webhook endpoint |
| `list_webhook_logs` | List recent delivery logs for a webhook |
| `list_webhook_events` | List all available webhook event types |
| `get_webhook_sample_payload` | Get a sample webhook payload for a specific event type |

</details>

<details>
<summary>Requisitions (6 tools)</summary>

| Tool | Description |
|------|-------------|
| `list_requisitions` | List all requisitions for your account |
| `get_requisition` | Get detailed information about a specific requisition |
| `list_requisition_fields` | List default and custom field definitions for requisitions |
| `create_requisition` | Create a new requisition (supports linked groups via head_count) |
| `update_requisition` | Update an existing requisition |
| `close_requisition` | Close a requisition |

</details>

<details>
<summary>Autocomplete (6 tools)</summary>

| Tool | Description |
|------|-------------|
| `search_companies` | Search companies by name |
| `list_industries` | List all available industries |
| `search_locations` | Search locations by query |
| `search_institutions` | Search academic institutions by name |
| `search_disciplines` | Search academic disciplines by name |
| `list_degrees` | List all available academic degrees |

</details>

## Development

```bash
# Use correct Node version
nvm use

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run tests
npm test

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node build/index.js
```

### Connecting locally

To test your local build with an AI client instead of the published package:

#### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "kula": {
      "command": "node",
      "args": ["/absolute/path/to/kula-mcp/build/index.js"],
      "env": {
        "KULA_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

<details>
<summary>With Cursor</summary>

Edit `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "kula": {
      "command": "node",
      "args": ["/absolute/path/to/kula-mcp/build/index.js"],
      "env": {
        "KULA_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

</details>

<details>
<summary>With Claude Code</summary>

```bash
claude mcp add kula -- node /absolute/path/to/kula-mcp/build/index.js
```

Then set `KULA_API_KEY` in your environment.

</details>

> **Note:** The server uses STDIO transport, so there's no hot-reload. After rebuilding (`npm run build` or via `npm run dev`), restart the MCP client to pick up changes.

## License

MIT

TDQS

A3.5/5.0

Scored across 84 tools

Disambiguation5/5

Each tool has a distinct, purpose-specific name and detailed description that clearly differentiates it from others. There is no overlap; even similar operations like 'list_candidates' vs 'search_candidates' are explained with different use cases.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern (e.g., cancel_interview, create_candidate, get_job). No mixing of casing or irregular naming is observed.

Tool Count1/5

84 tools is extremely high for an MCP server, far exceeding the typical 3-15 range. While the domain is broad, this count is excessive and likely to overwhelm agents and reduce coherence.

Completeness5/5

The tool set covers the full lifecycle of recruiting: candidates, applications, interviews, jobs, requisitions, users, webhooks, and reference data (skills, locations, etc.). CRUD operations are present for core entities, with additional utilities like searching and webhook management. No obvious gaps are apparent.

Maintenance

ActivityNo data
ResponsivenessOutdated data