Greenhouse MCP Server 🌱

An MCP (Model Context Protocol) server for interacting with the Greenhouse Harvest API. This server enables AI agents to manage recruitment workflows through Greenhouse's applicant tracking system.

Features

The Greenhouse MCP server provides tools for:

Jobs Management

• list_jobs - List all jobs with filtering options
• get_job - Get detailed information about a specific job

Candidate Management

• list_candidates - Search and list candidates
• get_candidate - Get detailed candidate information
• create_candidate - Add new candidates to the system
• update_candidate - Update existing candidate information
• add_note_to_candidate - Add notes to candidate profiles

Application Tracking

• list_applications - List applications with filtering
• get_application - Get detailed application information
• advance_application - Move applications through hiring stages
• reject_application - Reject applications with reasons
• add_note_to_application - Add notes to applications

Organization Data

• list_departments - List all departments
• list_offices - List all offices
• list_users - List Greenhouse users

Installation

Prerequisites

• Python 3.9+
• Greenhouse OAuth credentials (obtain from your Greenhouse admin panel)

Option 1: Install via pip

pip install greenhouse-mcp

Option 2: Install from source

git clone https://github.com/yourusername/greenhouse-mcp.git
cd greenhouse-mcp
pip install -e .

Option 3: Using npx (recommended)

npx greenhouse-mcp start <CLIENT_ID> <CLIENT_SECRET>

Configuration

Option 1: Environment Variables

Create a .env file in your project root:

GREENHOUSE_CLIENT_ID=your_client_id_here
GREENHOUSE_CLIENT_SECRET=your_client_secret_here
GREENHOUSE_BASE_URL=https://harvest.greenhouse.io/v1  # Optional, this is the default

Option 2: Command Line Arguments

npx greenhouse-mcp start <CLIENT_ID> <CLIENT_SECRET>

Usage

Running Locally

# Using npx (recommended)
npx greenhouse-mcp start <CLIENT_ID> <CLIENT_SECRET>

# Using pip
pip install greenhouse-mcp
greenhouse-mcp

# Using Python directly
python -m src.greenhouse_mcp

Using with Claude Desktop

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

{
  "mcpServers": {
    "greenhouse": {
      "command": "npx",
      "args": ["greenhouse-mcp", "start", "<CLIENT_ID>", "<CLIENT_SECRET>"]
    }
  }
}

Using with MCPD

1. Install MCPD:

npm install -g @modelcontextprotocol/mcpd

2. Add the server to MCPD:

mcpd add greenhouse-mcp

3. Configure environment variables:

mcpd config args set greenhouse-mcp --env GREENHOUSE_CLIENT_ID=your_client_id_here
mcpd config args set greenhouse-mcp --env GREENHOUSE_CLIENT_SECRET=your_client_secret_here

4. Start the MCPD daemon:

mcpd daemon

The server will be available at http://localhost:8090 with API documentation at /docs.

Example Usage

Once connected to an AI assistant, you can use natural language to interact with Greenhouse:

"List all open engineering jobs"
"Show me candidates who applied in the last week"
"Get details for candidate ID 12345"
"Add a note to application 67890 saying 'Strong technical skills, schedule second interview'"
"Advance application 11111 to the next stage"

API Rate Limiting

The server automatically handles Greenhouse API rate limits:

• Maximum 50 requests per 10 seconds
• Automatic retry with exponential backoff on rate limit errors
• Respects Retry-After headers

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/yourusername/greenhouse-mcp.git
cd greenhouse-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Copy environment variables
cp .env.example .env
# Edit .env with your API key

Running Tests

pytest tests/

Code Quality

# Format code
black src/

# Lint
ruff check src/

Security Notes

• Never commit your API key to version control
• Use environment variables or secure secret management
• The server only accepts connections from localhost by default
• All API requests use HTTPS

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

License

MIT License - see LICENSE file for details

Support

For issues related to:

• This MCP server: Open an issue on GitHub
• Greenhouse API: Consult Greenhouse API documentation
• MCP Protocol: Visit Model Context Protocol docs
• FastMCP: Check FastMCP documentation