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
- Install dependencies:
npm install
- Configure environment variables:
- Copy
.env.exampleto.env - Add your Greenhouse API key to
.env:
GREENHOUSE_API_KEY=your_api_key_here
- Build the project:
npm run build
- Start the server:
npm start
Deployment
GitHub Deployment (Recommended)
-
Fork or clone this repository to your GitHub account.
-
Set up GitHub repository secrets:
- Go to your repository's Settings > Secrets and variables > Actions
- Add a new secret named
GREENHOUSE_API_KEYwith your API key
-
Enable GitHub Actions:
- Go to your repository's Actions tab
- Enable workflows if they're not already enabled
-
Push your code to the main branch:
git add .
git commit -m "Initial commit"
git push origin main
-
The GitHub Actions workflow will automatically:
- Build and test your code
- Create a Docker image
- Push the image to GitHub Container Registry (ghcr.io)
-
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
-
Make sure you have Docker and Docker Compose installed on your system.
-
Configure your environment:
- Ensure your
.envfile contains the correctGREENHOUSE_API_KEY - The
.envfile will be used by Docker Compose for environment variables
- Ensure your
-
Build and start the container:
docker-compose up -d
- Check the logs:
docker-compose logs -f
- Stop the server:
docker-compose down
Manual Deployment
For manual deployment on a server:
-
Install Node.js (v20 or later) on your server
-
Clone the repository:
git clone <repository-url>
cd mcp-greenhouse
- Install dependencies:
npm install
- Set up environment variables:
cp .env.example .env
# Edit .env with your Greenhouse API key
- Build the project:
npm run build
- 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 pagepage(optional): Page number
list_applications
Lists applications in Greenhouse with filtering options.
Parameters:
job_id(optional): Filter by job IDstatus(optional): Filter by application status
move_application
Moves an application to a different stage.
Parameters:
application_id(required): ID of the application to movestage_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