@kula-ai/mcp-server

An MCP (Model Context Protocol) server for the Kula 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):

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

Add to ~/.cursor/mcp.json:

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

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

Then set KULA_API_KEY in your environment.

Manual

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.

Available Tools

51 tools across 13 categories:

| 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) |

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

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

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

| 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 |

| 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 |

| 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 |

| 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 |

| 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 |

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

| 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 |

| 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 |

| 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 |

Development

# 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:

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

Edit ~/.cursor/mcp.json:

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

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

Then set KULA_API_KEY in your environment.

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