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