Greenhouse MCP Server

A Model Context Protocol (MCP) server implementation for the Greenhouse Harvest API. This server provides tools for interacting with Greenhouse's recruitment and applicant tracking system through MCP.

Features

• List jobs with filtering options

• List candidates with pagination

• List applications with filtering

• Move applications between stages

• More features coming soon!

Local Development Setup

1. Install dependencies:

2. Configure environment variables:

• Copy .env.example to .env

• Add your Greenhouse API key to .env:

3. Build the project:

4. Start the server:

Deployment

GitHub Deployment (Recommended)

1. Fork or clone this repository to your GitHub account.

2. Set up GitHub repository secrets:

   • Go to your repository's Settings > Secrets and variables > Actions

   • Add a new secret named GREENHOUSE_API_KEY with your API key

3. Enable GitHub Actions:

   • Go to your repository's Actions tab

   • Enable workflows if they're not already enabled

4. Push your code to the main branch:

5. The GitHub Actions workflow will automatically:

   • Build and test your code

   • Create a Docker image

   • Push the image to GitHub Container Registry (ghcr.io)

6. To use the deployed container:

Using Docker Locally

1. Make sure you have Docker and Docker Compose installed on your system.

2. Configure your environment:

   • Ensure your .env file contains the correct GREENHOUSE_API_KEY

   • The .env file will be used by Docker Compose for environment variables

3. Build and start the container:

4. Check the logs:

5. Stop the server:

Manual Deployment

For manual deployment on a server:

1. Install Node.js (v20 or later) on your server

2. Clone the repository:

3. Install dependencies:

4. Set up environment variables:

5. Build the project:

6. Start with PM2 (recommended for production):

Available Tools

list_jobs

Lists all jobs in Greenhouse with optional status filtering.

Parameters:

• status (optional): Filter jobs by status ('open', 'closed', 'draft')

list_candidates

Lists candidates in Greenhouse with pagination support.

Parameters:

• per_page (optional): Number of candidates per page

• page (optional): Page number

list_applications

Lists applications in Greenhouse with filtering options.

Parameters:

• job_id (optional): Filter by job ID

• status (optional): Filter by application status

move_application

Moves an application to a different stage.

Parameters:

• application_id (required): ID of the application to move

• stage_id (required): ID of the target stage

Health Check

The server provides a health check endpoint at /tools that returns the list of available tools.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT