Merge MCP Server
This MCP (Model Context Protocol) server provides integration between Merge API and any LLM provider supporting the MCP protocol (e.g., Claude for Desktop), allowing you to interact with your Merge data using natural language.
✨ Features
- Query Merge API entities using natural language
- Get information about your Merge data models and their fields
- Create and update entities through conversational interfaces
- Support for multiple Merge API categories (HRIS, ATS, etc.)
📦 Installation
Prerequisites
- A Merge API key and account token
- Python 3.10 or higher
- uv
Install uv
with standalone installer:
or through pip:
🔌 MCP setup
Here is an example config file which you can use to set up Merge MCP.
Note: If "uvx" command does not work, try absolute path (i.e. /Users/username/.local/bin/uvx)
Example Claude Desktop configuration
- Ensure you have
uvx
installed - Download Claude Desktop from the official website
- Once downloaded, open the app and follow the instructions to set up your account
- Navigate to Settings → Developer → Edit Config. This should open a file named
claude_desktop_config.json
in a text editor. - Copy the MCP server setup JSON above and paste it into the text editor
- Replace
your_api_key
andyour_account_token
with your actual Merge API key and Linked Account token. You will also need to replaceuvx
with the absolute path to the command in the config file (i.e./Users/username/.local/bin/uvx
). You can find the absolute path by runningwhich uvx
through your terminal. - Save the config file
- Restart Claude Desktop to see your tools. The tools may take a minute to appear
Example Python client configuration
- Setting up your environment
- Setting up your API keys
- Create a
client.py
file and add the following code
- Add a
connect_to_server
function to the MCPClient class
- Add a
process_query
function to the MCPClient class
- Add a
chat_loop
function to the MCPClient class
- Add a
cleanup
function to the MCPClient class
- Add a
main
function to theclient.py
file as the main entry point
- Running the client
🔍 Scopes
Scopes determine which tools are enabled on the MCP server and are used to control access to different parts of the Merge API. If no scopes are specified, all available scopes will be enabled.
When starting the server, you can specify which scopes to enable. This is done by passing the --scopes
flag with a list of scopes.
Scope Format
Scopes in the Merge MCP server follow a specific format based on the Merge API category and common model names. Each scope is formatted as:
Where:
<category>
is the Merge API category (e.g.,hris
,ats
,accounting
)<CommonModel>
is the name of the Merge Common Model (e.g.,Employee
,Candidate
,Account
)<permission>
is eitherread
orwrite
(optional - if not specified, all permissions are granted)
Examples of valid scopes:
hris.Employee:read
- Allows reading employee data from HRIS categoryats.Candidate:write
- Allows creating or updating candidate data in ATS categoryaccounting.Account
- Allows all operations on account data in Accounting category
You can combine multiple scopes to grant different permissions.
Important Notes on Scope Availability
The available scopes depend on your Merge API account configuration and the models the Linked Account has access to. Scopes must be cross-referenced with enabled scopes on your Linked Account:
- Category Mismatch: If you specify a scope for a category that doesn't match your Linked Account (e.g., using
ats.Job
with an HRIS Linked Account), no tools for that scope will be returned. - Permission Mismatch: If you request a permission that isn't enabled for your Linked Account (e.g., using
hris.Employee:write
when only read access is enabled), tools requiring that permission won't be returned. - Validation: The server will automatically validate your requested scopes against what's available in your Linked Account and will only enable tools for valid, authorized scopes.
Scopes typically correspond to different models or entity types in the Merge API, and they control both read and write access to these entities.
🚀 Available Tools
The Merge MCP server provides access to various Merge API endpoints as tools. The available tools depend on your Merge API category (HRIS, ATS, etc.) and the scopes you have enabled.
Tools are dynamically generated based on your Merge API schema and include operations for:
- Retrieving entity details
- Listing entities
- Creating new entities
- Updating existing entities
- And more, based on your specific Merge API configuration
Note: Download tools are not currently supported. This is a known limitation and will be addressed in a future release.
🔑 Environment Variables
The following environment variables are used by the Merge MCP server:
MERGE_API_KEY
: Your Merge API keyMERGE_ACCOUNT_TOKEN
: Your Merge Linked Account tokenMERGE_TENANT
(Optional): The Merge API tenant. Valid values areUS
,EU
, andAPAC
. Defaults toUS
.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Provides integration between Merge API and LLM providers supporting the MCP protocol, allowing natural language interaction with Merge data across HRIS, ATS, and other categories.
Related MCP Servers
- -securityAlicense-qualityAn MCP server that provides tools to load and fetch documentation from any llms.txt source, giving users full control over context retrieval for LLMs in IDE agents and applications.Last updated -177PythonMIT License
- -securityFlicense-qualityAn MCP server that connects to Backlog API, providing functionality to search, retrieve, and update issues through natural language commands.Last updated -241JavaScript
- -securityFlicense-qualityA customized MCP server that enables integration between LLM applications and documentation sources, providing AI-assisted access to LangGraph and Model Context Protocol documentation.Last updated -Python
- AsecurityAlicenseAqualityThe APISIX Model Context Protocol (MCP) server bridges large language models (LLMs) with the APISIX Admin API.Last updated -316716TypeScriptApache 2.0