open-greenhouse-mcp 0.3.0

Comprehensive MCP server for the full Greenhouse API

open-greenhouse-mcp

Connect your AI assistant to Greenhouse. MCP (Model Context Protocol) lets AI tools like Claude, Cursor, and others talk directly to your software. This server gives them full access to Greenhouse — 175 tools covering recruiting pipelines, candidate search, analytics, batch operations, and the complete Greenhouse API.

Works with

• Claude Desktop and Claude Code
• Cursor
• Any MCP-compatible client

What Can It Do?

Ask your AI assistant questions like these — it handles the Greenhouse API calls automatically:

You say	The tool used
"Show me the pipeline for the Engineering Manager role"	pipeline_summary
"What are our conversion rates for this job?"	pipeline_metrics
"Find that candidate Sarah from Google"	search_candidates_by_name
"What needs my attention this week?"	candidates_needing_action
"Which sources are actually producing hires?"	source_effectiveness
"How long does it take us to hire?"	time_to_hire
"Reject all 30 stale candidates from that old req"	bulk_reject
"Pull up this candidate's resume"	read_candidate_resume

Plus 148 tools covering every Greenhouse Harvest API endpoint, 13 Job Board tools, 6 Ingestion API tools, and 8 webhook management tools.

See it in action

Three queries — pipeline view, source analysis, time-to-hire metrics — each resolved in a single tool call. See more examples.

Quick Start

pip install open-greenhouse-mcp

Or install from source:

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

Set your API key:

export GREENHOUSE_API_KEY=your-harvest-api-key

Add to your MCP client config (Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json, Cursor: Settings > MCP):

{
  "mcpServers": {
    "greenhouse": {
      "command": "open-greenhouse-mcp",
      "env": {
        "GREENHOUSE_API_KEY": "your-harvest-api-key"
      }
    }
  }
}

Restart your client and start asking questions.

Composite Tools (13 tools)

High-level tools that match how recruiters actually work. These combine multiple API calls into single operations.

Tool	What it does
pipeline_summary	Full pipeline view — candidates grouped by stage with names, days-in-stage, last activity
candidates_needing_action	Find stale applications and interviews missing scorecards
stale_applications	Applications with no activity for N days, sorted by stalest
pipeline_metrics	Conversion rates, hire/rejection rates, time-in-stage per stage
source_effectiveness	Which candidate sources produce the best hire rates
time_to_hire	Average, median, min, max days from application to hire
bulk_reject	Reject multiple applications in one call with rate-limit handling
bulk_tag	Tag multiple candidates in one call
bulk_advance	Advance multiple applications to next stage
search_candidates_by_name	Find candidates by first or last name
search_candidates_by_email	Look up a candidate by exact email
read_candidate_resume	Download and return a candidate's most recent resume
download_attachment	Download any Greenhouse attachment by URL

Harvest API (148 tools)

Full coverage of every Greenhouse Harvest API endpoint.

Category	Tools	Category	Tools
Candidates	15	Applications	14
Jobs	4	Job Posts	7
Job Stages	3	Job Openings	5
Offers	5	Scorecards	3
Interviews	6	Users	8
User Permissions	6	User Roles	1
Departments	4	Offices	4
Custom Fields	9	Sources	1
Rejection Reasons	1	Email Templates	2
Tags	6	Activity Feed	1
EEOC	2	Demographics	11
Approvals	6	Hiring Team	4
Prospect Pools	2	Close Reasons	1
Tracking Links	1	Education	3

Other APIs

Job Board API (13 tools)

List boards, jobs, posts, departments, offices, and questions from public job boards.

Ingestion API (6 tools)

Submit applications and prospects programmatically. Requires GREENHOUSE_ON_BEHALF_OF.

Webhook Management (8 tools)

Create, list, update, and delete webhook subscriptions. Query received events with filtering.

Authentication

Credential	Access
GREENHOUSE_API_KEY	Full Harvest API, Ingestion API, Webhooks
GREENHOUSE_BOARD_TOKEN	Job Board API only (public, no auth required)

Set at least one. Both can be configured simultaneously.

You can find your API key in Greenhouse under Configure > Dev Center > API Credential Management.

Tool Profiles

Control which tools are available based on your use case:

Profile	Tools	Use case
full (default)	175	Admin or developer with full API access
recruiter	121	Day-to-day recruiting — pipeline management, candidate interaction, bulk operations
read-only	97	Reporting, evaluation, or safe trial against production

{
  "mcpServers": {
    "greenhouse": {
      "command": "open-greenhouse-mcp",
      "env": {
        "GREENHOUSE_API_KEY": "your-harvest-api-key",
        "GREENHOUSE_TOOL_PROFILE": "recruiter"
      }
    }
  }
}

Recruiter profile includes: all read tools, composite workflows, pipeline management (reject, advance, move, hire), bulk operations, candidate notes/tags/attachments, interview scheduling, prospect management.

Recruiter profile excludes: job creation/editing, user management, custom field configuration, department/office changes, candidate deletion, webhook management, and other admin operations.

Read-only profile skips all write operations. GREENHOUSE_READ_ONLY=true is a shorthand for GREENHOUSE_TOOL_PROFILE=read-only.

Write Operations and Audit Trail

Tools that modify data in Greenhouse (create, update, delete, reject, advance) are clearly separated from read-only tools. When using write tools:

• Set GREENHOUSE_ON_BEHALF_OF to your Greenhouse user ID. This adds an audit trail — all write operations are recorded in Greenhouse as performed by that user, not just "API".
• Bulk operations (bulk_reject, bulk_tag, bulk_advance) include built-in rate limiting to stay under Greenhouse's API limits.
• Destructive actions like candidate deletion or application rejection require explicit IDs — the server never infers targets.

Logging

Structured JSON logging to stderr for observability. Controlled by environment variables:

GREENHOUSE_LOG_LEVEL=info      # debug, info, warning (default), error
GREENHOUSE_LOG_FILE=/var/log/greenhouse-mcp.log  # optional, defaults to stderr

Each log line is a JSON object:

{"ts": "2026-04-14T12:31:58", "level": "info", "event": "api_call", "method": "GET", "url": "...", "status": 200, "latency_ms": 245.0}

API calls are logged at info level for 2xx, warning for 4xx, and error for 5xx. The server startup log includes the active tool profile and number of registered tools.

Webhook Receiver

The built-in webhook receiver stores Greenhouse events in SQLite for querying via MCP tools.

# Set your webhook secret (from Greenhouse settings)
export GREENHOUSE_WEBHOOK_SECRET=your-secret

# Start the receiver
open-greenhouse-mcp-receiver

Configure the webhook URL in Greenhouse to point to http://your-host:8080/webhooks/greenhouse.

Development

git clone https://github.com/benmonopoli/open-greenhouse-mcp.git
cd open-greenhouse-mcp
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Lint
ruff check src/ tests/

# Type check
mypy src/greenhouse_mcp/ --ignore-missing-imports

Feedback and Issues

• Bug reports and feature requests: Open an issue
• Questions and discussion: Start a discussion
• Security vulnerabilities: See SECURITY.md

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT License -- Ben Monopoli. See LICENSE.

This project follows the Contributor Covenant Code of Conduct.