willo-mcp-server

Willo MCP Server

An MCP (Model Context Protocol) server that integrates with the Willo API to manage interviews and participants. This server provides three main tools for listing interviews, listing participants, and getting detailed participant information.

Installation

Install via npm:

npm install -g willo-mcp-server

Or install locally:

npm install willo-mcp-server

Setup

• Get your Willo API key from your Willo account
• Set the API key as an environment variable:

export WILLO_API_KEY="your-api-key-here"

Usage

The server provides three tools:

list_interviews

Lists interviews from the Willo API with optional filters.

Parameters:

• department (optional): Key of the department to filter by
• owner (optional): Key of the owner to filter by
• search (optional): Search by title, owner email, department name
• ordering (optional): Comma separated list of fields to order by
• page_size (optional): Number of results per page (1-30)
• api_key (optional): API key if not set in environment

Example response:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "key": "1e2048a686804049b128f1357c559cbf",
      "title": "Researcher",
      "owner": {
        "key": "d62a87cd963f46a0b6d020947fd1dcf5",
        "email": "[e-mail]",
        "full_name": "Marie Curie"
      },
      "organisation": {
        "key": "78d0380bb05f40fe9b5103437ef3284d",
        "name": "Willo"
      },
      "department": {
        "key": "b323b3e3bf424da3ac0b08bd534c91e2",
        "name": "HR"
      },
      "invite_link": "https://willotalent.com/invite/fhf3v/"
    }
  ]
}

list_participants

Lists participants with optional filters.

Parameters:

• interview (optional): Key of the interview to filter by
• department (optional): Key of the department to filter by
• owner (optional): Key of the owner to filter by
• search (optional): Search by name, email, interview title
• page_size (optional): Number of results per page (1-30)
• api_key (optional): API key if not set in environment

get_participant

Gets detailed information for a specific participant including answers and transcripts.

Parameters:

• participant_id (required): Key of the participant to get details for
• api_key (optional): API key if not set in environment

find_participants_by_status

Finds all participants with a specific status across all interviews. This function combines multiple API calls to search through all participants and filter by their exact status.

Parameters:

• status (required): Exact Willo status to filter by
• department (optional): Key of the department to filter by
• owner (optional): Key of the owner to filter by
• interview (optional): Key of specific interview to search within
• delay_ms (optional): Delay between API calls in milliseconds (default: 200ms, min: 100ms)
• api_key (optional): API key if not set in environment

Valid Status Values:

• "Default" - New registrations, haven't started interview
• "Received" - Completed interview, pending evaluation
• "Accepted" - Passed evaluation, approved candidate
• "Rejected" - Failed evaluation, declined candidate

Example Usage:

// Find all candidates pending evaluation
find_participants_by_status({ status: "Received" })

// Find all accepted candidates
find_participants_by_status({ status: "Accepted" })

// Find all rejected candidates  
find_participants_by_status({ status: "Rejected" })

// Find new/incomplete interviews
find_participants_by_status({ status: "Default" })

// Find received candidates in specific department
find_participants_by_status({ 
  status: "Received", 
  department: "dept_key_123" 
})

// Find accepted candidates with longer delay to avoid rate limiting
find_participants_by_status({ 
  status: "Accepted", 
  delay_ms: 500 
})

Rate Limiting Protection: This function includes built-in rate limiting protection:

• Automatic retry with exponential backoff for 429 errors
• Configurable delays between API calls
• Batch processing to avoid overwhelming the API
• Graceful error handling that continues processing other participants

Configuration

Claude Desktop

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

{
  "mcpServers": {
    "willow": {
      "command": "npx",
      "args": ["willo-mcp-server"],
      "env": {
        "WILLO_API_KEY": "your-api-key"
      }
    }
  }
}

Local Development

If you're running from source:

{
  "mcpServers": {
    "willow": {
      "command": "node",
      "args": ["/path/to/willo-mcp-server/dist/index.js"],
      "env": {
        "WILLO_API_KEY": "your-api-key"
      }
    }
  }
}

API Reference

This server integrates with the Willo API v2. For more information about the API endpoints and responses, refer to the Willo API documentation.

Requirements

• Node.js 18.0.0 or higher
• Valid Willo API key

License

MIT