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:

npm install

2. Configure environment variables:

• Copy .env.example to .env
• Add your Greenhouse API key to .env:

GREENHOUSE_API_KEY=your_api_key_here

3. Build the project:

npm run build

4. Start the server:

npm start

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:

git add .
git commit -m "Initial commit"
git push origin main

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:

docker pull ghcr.io/your-username/mcp-greenhouse:latest
docker run -p 3001:3001 -e GREENHOUSE_API_KEY=your_api_key ghcr.io/your-username/mcp-greenhouse:latest

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:

docker-compose up -d

4. Check the logs:

docker-compose logs -f

5. Stop the server:

docker-compose down

Manual Deployment

For manual deployment on a server:

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

2. Clone the repository:

git clone <repository-url>
cd mcp-greenhouse

3. Install dependencies:

npm install

4. Set up environment variables:

cp .env.example .env
# Edit .env with your Greenhouse API key

5. Build the project:

npm run build

6. Start with PM2 (recommended for production):

npm install -g pm2
pm2 start dist/index.js --name mcp-greenhouse

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