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](QUICKSTART_LOCAL.md) - 5-minute quick start
• [LOCAL_TESTING.md](LOCAL_TESTING.md) - Comprehensive testing guide
• [TESTING_SUMMARY.md](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

1. Clone this repository.
2. Create a virtual environment:

    python3 -m venv .venv
    source .venv/bin/activate

1. Install dependencies:

    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 to https://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:

./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.

{
  "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:

1. Run the server in streamable HTTP mode:

    ./run_http.sh

This will start the server on port 8005.

1. Configure Antigravity to connect to the running server:

    {
      "mcpServers": {
        "lever": {
          "url": "http://localhost:8005/mcp"
        }
      }
    }

SSE (Legacy)

The SSE transport is deprecated but still supported:

1. Run the server in SSE mode:

    ./run_sse.sh

This will start the server on port 8005.

1. Configure Antigravity to connect to the running server:

    {
      "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 [email protected]

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.