Recruitee MCP Server

Model Context Protocol (MCP) server for Recruitee – advanced search, reporting, and analytics for recruitment data.

---

🚀 Overview

The Model Context Protocol (MCP) is rapidly becoming the standard for connecting AI agents to external services. This project implements an MCP server for Recruitee, enabling advanced, AI-powered search, filtering, and reporting on recruitment data.

Unlike basic CRUD wrappers, this server focuses on the tasks where LLMs and AI agents excel: summarizing, searching, and filtering. It exposes a set of tools and prompt templates, making it easy for any MCP-compatible client to interact with Recruitee data in a structured, agent-friendly way.

---

✨ Features

• Advanced Candidate Search & Filtering
  Search for candidates by skills, status, talent pool, job, tags, and more. Example:
  "Find candidates with Elixir experience who were rejected due to salary expectations."

• Recruitment Summary Reports
  Generate summaries of recruitment activities, such as time spent in each stage, total process duration, and stage-by-stage breakdowns.

• Recruitment Statistics
  Calculate averages and metrics (e.g., average expected salary for backend roles, average time to hire, contract type stats).

• General Search
  Quickly find candidates, recruitments, or talent pools by name or attribute.

• Prompt Templates
  Exposes prompt templates for LLM-based clients, ensuring consistent and high-quality summaries.

---

🛠 Example Queries

• Find candidates with Elixir experience who were rejected due to salary expectations.
• Show me their personal details including CV URL.
• Why was candidate 'X' disqualified and at what stage?
• What are the other stages for this offer?
• Show candidates whose GDPR certification expires this month.
• What's time to fill sales assistant offer?
• Create a pie chart with sources for AI engineer offer.
• Create a recruitment report.

---

🧑‍💻 Implementation

• Language: Python
• Framework: FastMCP
• API: Recruitee Careers Site API
• Schemas: All MCP tool schemas are generated from Pydantic models, with rich metadata for LLMs.

The server retrieves and processes data from Recruitee, exposing it via MCP tools. Summaries are composed by the client using provided prompt templates.

---

🚦 Transport Methods

• stdio – For local development and testing.
• streamable-http – For remote, production-grade deployments (recommended).
• SSE – Supported but deprecated in some MCP frameworks.

---

📚 Resources

• Recruitee MCP Server (GitHub)
• Recruitee API Docs
• Model Context Protocol (MCP)
• FastMCP Framework
• MCP Server for Charts

---

🤝 Contributing

Contributions, issues, and feature requests are welcome!

---

📝 License

This project is MIT licensed.

---

Empower your AI agents with advanced recruitment data access and analytics.

🧪 Usage

💡 Tip: For data visualization, combine this with chart-specific MCP servers like mcp-server-chart

Local (stdio)

1. Configure your MCP client:

   Copy

   {
     "mcpServers": {
       "recruitee": {
         "command": "/path/to/.venv/bin/python",
         "args": ["/path/to/recruitee-mcp-server/src/app.py", "--transport", "stdio"]
       }
     }
   }

2. Run with mcp-cli:

   Copy

   mcp-cli chat --server recruitee --config-file /path/to/mcp-cli/server_config.json

Remote (streamable-http)

1. Use mcp-remote:

   Copy

   {
     "mcpServers": {
       "recruitee": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://recruitee-mcp-server.fly.dev/mcp/",
           "--header",
           "Authorization: Bearer ${MCP_BEARER_TOKEN}"
         ],
         "env": {
           "MCP_BEARER_TOKEN": "KEY"
         }
       }
     }
   }

2. or use directly if client supports bearer token authorization

   Copy

   {
     "mcpServers": {
       "recruitee": {
         "transport": "streamable-http",
         "url": "https://recruitee-mcp-server.fly.dev/mcp"
       }
     }
   }

---

☁️ Deployment

Deploy to Fly.io

1. Set your secrets in .env

2. Create a volume

   Copy

   make create_volume

3. Deploy:

   Copy

   flyctl auth login
   make deploy

---