Greenhouse MCP Server

# 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: ```bash 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: ```bash npm run build ``` 4. Start the server: ```bash 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: ```bash 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: ```bash 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: ```bash docker-compose up -d ``` 4. Check the logs: ```bash docker-compose logs -f ``` 5. Stop the server: ```bash 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: ```bash git clone <repository-url> cd mcp-greenhouse ``` 3. Install dependencies: ```bash npm install ``` 4. Set up environment variables: ```bash cp .env.example .env # Edit .env with your Greenhouse API key ``` 5. Build the project: ```bash npm run build ``` 6. Start with PM2 (recommended for production): ```bash 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