Lever MCP Server
An MCP server for interacting with the Lever.co API. This server allows AI agents to list candidates, retrieve candidate details, create job requisitions, and send fun themed emails.
🎯 Features
This Python MCP server provides:
- Lever candidate and job requisition management
- Gmail integration with OAuth 2.0 and browser agent polling
- Themed HTML email templates (birthday, pirate, space, medieval, superhero, tropical)
- Full MCP protocol compatibility
🚀 Quick Start: Local OAuth Testing
Want to test the OAuth flow locally before deploying? See:
- QUICKSTART_LOCAL.md - 5-minute quick start
- LOCAL_TESTING.md - Comprehensive testing guide
- TESTING_SUMMARY.md - What was built and why
Prerequisites
- Python 3.10 or higher
- A Lever API Key (generated from Lever Settings > Integrations and API > API Credentials)
Installation
- Clone this repository.
- Create a virtual environment:
bash python3 -m venv .venv source .venv/bin/activate - Install dependencies:
bash pip install -e .
Configuration
The server requires the following environment variables:
Lever API Configuration
LEVER_API_KEY: Your Lever API key.LEVER_API_BASE_URL(Optional): The base URL for the API. Defaults tohttps://api.lever.co/v1.
Gmail OAuth Configuration (Optional)
For email sending functionality:
- GOOGLE_CLIENT_ID: Your Google OAuth client ID
- GOOGLE_CLIENT_SECRET: Your Google OAuth client secret
- OAUTH_REDIRECT_URI (Optional): OAuth redirect URI. Defaults to http://localhost:8080/oauth/callback
- TOKEN_STORAGE_PATH (Optional): Path to store OAuth tokens. Defaults to ./.oauth_tokens
See OAUTH_SETUP.md for detailed Gmail OAuth setup instructions.
Sandbox Environment
To use the Lever Sandbox environment:
1. Set LEVER_API_BASE_URL to https://api.sandbox.lever.co/v1.
2. Use an API key generated from your Sandbox account.
Usage
To run the server:```bash
./run.sh
## Using with Antigravity
To connect this server to Antigravity, you need to add it to your MCP settings configuration.
1. Open your Antigravity MCP settings (usually `~/.antigravity/mcp_settings.json` or via the UI).
2. Add the following configuration. **Important:** Use absolute paths.```json
{
"mcpServers": {
"lever": {
"command": "/bin/bash",
"args": ["/Users/andrew/focus/ai/apps/lever-mcp/run.sh"],
"env": {
"LEVER_API_KEY": "your_api_key_here",
"LEVER_API_BASE_URL": "https://api.sandbox.lever.co/v1"
}
}
}
}
Note: Replace /Users/andrew/focus/ai/apps/lever-mcp/run.sh with the actual absolute path to your run.sh file.
Verification and Logs
Trigger Prompt:
Once connected, you can ask Antigravity:
> "Can you list the current job candidates from Lever?"
Viewing Logs:
- MCP Server Logs: The server logs to stderr. In Antigravity, these logs are typically visible in the MCP Server logs panel or the application logs.
- Application Logs: Check lever_mcp.log if you configured file logging, otherwise they appear in the console output of the server.
Running Manually (HTTP Transport)
If you prefer to run the server manually in your terminal and have Antigravity connect to it, you can use the HTTP transport.
Streamable HTTP (Recommended)
The streamable-http transport is the modern, recommended approach for web deployments:
-
Run the server in streamable HTTP mode:
bash ./run_http.sh
This will start the server on port 8005. -
Configure Antigravity to connect to the running server:
json { "mcpServers": { "lever": { "url": "http://localhost:8005/mcp" } } }
SSE (Legacy)
The SSE transport is deprecated but still supported:
-
Run the server in SSE mode:
bash ./run_sse.sh
This will start the server on port 8005. -
Configure Antigravity to connect to the running server:
json { "mcpServers": { "lever": { "url": "http://localhost:8005/sse" } } }
Note: When running manually, you must ensure the LEVER_API_KEY environment variable is set in your terminal session before starting the server.
Available Tools
Lever API Tools
list_candidates
Lists candidates from your Lever account.
Parameters:
- limit (optional): Maximum number of candidates to return (default: 10)
- offset (optional): Pagination offset token
Example:```
List the first 20 candidates from Lever
#### `get_candidate`
Retrieves detailed information about a specific candidate.
**Parameters:**
- `candidateId` (required): The ID of the candidate to retrieve
**Example:**```
Get candidate details for ID abc123
create_requisition
Creates a new job requisition in Lever.
Parameters:
- title (required): Job title
- location (required): Job location
- team (required): Team name
Example:```
Create a requisition for Senior Software Engineer in San Francisco for the Engineering team
### Email Tools
#### `send_email`
Generates and sends a themed email via Gmail API with OAuth 2.0 authentication.
**Parameters:**
- `to` (required): Recipient email address
- `theme` (required): Email theme - one of: `birthday`, `pirate`, `space`, `medieval`, `superhero`, `tropical`
- `subject` (optional): Custom subject line (uses theme default if not provided)
- `cc` (optional): CC email addresses (comma-separated)
- `bcc` (optional): BCC email addresses (comma-separated)
- `access_token` (optional): OAuth access token from agent (on-behalf-of flow)
- `user_id` (optional): User identifier for token storage (default: "default")
**Returns:**
- If authenticated: Email sent status with message ID
- If not authenticated: Gmail API payload for manual sending
**Available Themes:**
- 🎉 **birthday**: Colorful birthday celebration email
- 🏴☠️ **pirate**: Pirate-themed message from the high seas
- 🚀 **space**: Cosmic greetings from outer space
- ⚔️ **medieval**: Royal proclamation in medieval style
- 🦸 **superhero**: Superhero alert with bold styling
- 🌴 **tropical**: Tropical paradise vibes
**Example:**```
Send a birthday themed email to friend@example.com
OAuth Integration:
- With Token: Provide access_token parameter to send email immediately
- Without Token: Returns Gmail API payload for manual sending
- See OAUTH_SETUP.md for setup instructions
get_oauth_url
Get OAuth authorization URL for Gmail access.
Parameters:
- user_id (optional): User identifier (default: "default")
Returns:
- Authorization URL and step-by-step instructions
Example:```
Get Gmail OAuth authorization URL
#### `exchange_oauth_code`
Exchange OAuth authorization code for access token.
**Parameters:**
- `code` (required): Authorization code from OAuth callback
- `user_id` (optional): User identifier (default: "default")
**Returns:**
- Token information and confirmation
**Example:**```
Exchange OAuth code abc123xyz for access token
check_oauth_status
Check OAuth authentication status.
Parameters:
- user_id (optional): User identifier (default: "default")
Returns:
- Authentication status and configuration info
Example:Check Gmail OAuth status
Note: Email tools do not require Lever API credentials and can be used independently.
