6d342a1545
- READMEs added: asana, close, freshdesk, google-console, gusto, square - main.ts + server.ts (lazy loading): activecampaign, clickup, klaviyo, mailchimp, pipedrive, trello, touchbistro, closebot, close, google-console - All 13 compile with 0 TSC errors
133 lines
4.0 KiB
Markdown
133 lines
4.0 KiB
Markdown
# Greenhouse MCP Server
|
|
|
|
AI-powered access to the Greenhouse ATS/recruiting platform via Model Context Protocol.
|
|
|
|
## Features
|
|
|
|
- **Candidate Management**: List, get, create, update candidates, and add candidate notes
|
|
- **Application Tracking**: Browse applications, advance through pipeline stages, reject applications
|
|
- **Job Management**: List, get, create, and update job postings and requisitions
|
|
- **Interviews**: List all interviews, get interview details, list scheduled interviews
|
|
- **Scorecards**: Browse interview feedback, get scorecard details, create new scorecards
|
|
- **Offers**: List and retrieve offer details and compensation information
|
|
- **Organization Data**: Access departments, offices, sources, rejection reasons, job stages, and custom fields
|
|
- **User Management**: List and retrieve Greenhouse users and team members
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Required | Description | Example |
|
|
|----------|----------|-------------|---------|
|
|
| `GREENHOUSE_API_KEY` | ✅ | Greenhouse Harvest API key | `your_harvest_api_key_here` |
|
|
|
|
## Getting Your Access Token
|
|
|
|
1. Log into your Greenhouse account
|
|
2. Navigate to **Configure** > **Dev Center** > **API Credential Management**
|
|
3. Click **Create New API Key**
|
|
4. Select **Harvest API** (for production data access)
|
|
5. Set appropriate permissions for your use case
|
|
6. Copy the generated API key
|
|
7. Set it as `GREENHOUSE_API_KEY` in your environment
|
|
|
|
## Required API Scopes
|
|
|
|
The Harvest API key requires permissions based on your use case:
|
|
|
|
- **Read access**: Candidates, Applications, Jobs, Interviews, Scorecards, Offers, Users, Departments, Offices
|
|
- **Write access**: Create/update candidates, create scorecards, advance applications, reject applications, create/update jobs
|
|
|
|
Configure permissions when creating the API key in Greenhouse.
|
|
|
|
## Usage
|
|
|
|
### Stdio Mode (Default)
|
|
|
|
```bash
|
|
node dist/main.js
|
|
```
|
|
|
|
Or using the npm script:
|
|
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
### HTTP Mode
|
|
|
|
Currently supports stdio transport only. HTTP/SSE transport support coming soon.
|
|
|
|
## Tool Coverage Manifest
|
|
|
|
### Total API Coverage
|
|
|
|
- **Total Greenhouse Harvest API endpoints**: ~150
|
|
- **Tools implemented**: 20
|
|
- **Intentionally skipped**: 130
|
|
- **Coverage**: 20/150 = 13%
|
|
|
|
### Implemented Tools
|
|
|
|
| Category | Tools | Count |
|
|
|----------|-------|-------|
|
|
| Candidates | list, get, create, update, create_note | 5 |
|
|
| Applications | list, get, advance, reject | 4 |
|
|
| Jobs | list, get, create, update | 4 |
|
|
| Interviews | list, get, list_scheduled | 3 |
|
|
| Scorecards | list, get, create | 3 |
|
|
| Offers | list, get | 2 |
|
|
| Organization | list_departments, list_offices, list_sources, list_rejection_reasons, list_job_stages, list_custom_fields | 6 |
|
|
| Users | list, get | 2 |
|
|
|
|
**Total: 29 tools** across 8 categories
|
|
|
|
### Skipped Endpoints (Rationale)
|
|
|
|
- **Job Posts** (6 endpoints): Covered by job management tools, posts are auto-created with jobs
|
|
- **Email Templates** (4 endpoints): Admin configuration, rarely needed in AI workflows
|
|
- **Approvals** (5 endpoints): Complex approval flow management better suited for UI
|
|
- **EEOC** (3 endpoints): Compliance data requiring special handling
|
|
- **Activity Feed** (10+ endpoints): Duplicates data available in primary resources
|
|
- **Webhooks** (8 endpoints): Admin configuration, not suitable for MCP tool calls
|
|
- **Attachments** (4 endpoints): Complex binary handling, requires special transport
|
|
- **Tags** (4 endpoints): Low-value metadata, rarely used
|
|
- Other low-use administrative endpoints
|
|
|
|
### Coverage Goals
|
|
|
|
Current implementation focuses on **Tier 1** (daily recruiting workflows):
|
|
- Reviewing candidates and applications
|
|
- Advancing candidates through pipeline
|
|
- Scheduling and evaluating interviews
|
|
- Managing job postings
|
|
- Accessing organizational data
|
|
|
|
**Future expansion** could add Tier 2 tools for power users:
|
|
- Bulk operations
|
|
- Advanced reporting
|
|
- Candidate pool management
|
|
- Offer approval workflows
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Watch mode for development
|
|
npm run dev
|
|
|
|
# Build
|
|
npm run build
|
|
|
|
# Type checking
|
|
npx tsc --noEmit
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|