项目简介

Merge API MCP服务器是一个基于Model Context Protocol (MCP) 构建的应用后端，它充当Merge API与支持MCP协议的LLM客户端（如Claude for Desktop）之间的桥梁。该服务器允许用户使用自然语言与Merge API中的各种数据实体进行交互，例如查询信息、创建或更新数据等。

主要功能点

自然语言查询Merge API实体: 用户可以使用自然语言提问，服务器会将问题转换为Merge API的查询，并返回相关数据。
Merge数据模型信息: 提供Merge API数据模型的结构和字段信息，帮助LLM理解可操作的数据类型。
会话式数据操作: 支持通过对话界面创建和更新Merge API中的实体数据。
多Merge API类别支持: 能够处理来自不同Merge API类别（如HRIS, ATS等）的数据请求。
工具集成: 将Merge API的各种操作封装成MCP工具，供LLM客户端调用。
动态工具生成: 根据Merge API的OpenAPI schema动态生成可用的工具。
作用域控制: 通过作用域 (Scopes) 管理对Merge API不同部分的访问权限，确保数据安全。

安装步骤

安装前提
- 拥有 Merge API 密钥 (API Key) 和账户令牌 (Account Token)。
- 确保已安装 Python 3.10 或更高版本。
- 安装 uv (推荐) 或 pip。

安装 uv (推荐，二选一)

使用独立安装脚本（macOS 和 Linux）：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

或使用 pip 安装：
```
pip install uv
```

配置 MCP 客户端

在您的 MCP 客户端配置文件中添加以下配置 (以 Claude Desktop 为例，在 Settings → Developer → Edit Config 中编辑)：

{
    "mcpServers": {
        "merge-mcp-server": {
            "command": "uvx",
            "args": ["merge-mcp"],
            "env": {
                "MERGE_API_KEY": "your_api_key",
                "MERGE_ACCOUNT_TOKEN": "your_account_token"
            }
        }
    }
}

配置参数说明:
- '"merge-mcp-server"': 服务器名称，可以自定义。
- '"command": "uvx"': 启动服务器的命令，这里假设 'uvx' 命令可用。如果 'uvx' 命令不可用，请尝试使用 'uvx' 的绝对路径 (例如: '/Users/username/.local/bin/uvx')。
- '"args": ["merge-mcp"]': 传递给 'uvx' 命令的参数，'merge-mcp' 是要运行的 Python 模块名。
- '"env"': 环境变量配置。
  - '"MERGE_API_KEY": "your_api_key"': 请替换为您的 Merge API 密钥。
  - '"MERGE_ACCOUNT_TOKEN": "your_account_token"': 请替换为您的 Merge 账户令牌。

配置作用域 (Scopes) (可选)

您可以通过配置作用域来限制 MCP 服务器可访问的 Merge API 功能。
在 'args' 数组中添加 '--scopes' 参数和要启用的作用域列表。

{
    "mcpServers": {
        "merge-mcp-server": {
            "command": "uvx",
            "args": [
                "merge-mcp",
                "--scopes",
                "ats.Job:read",
                "ats.Candidate",
                "ats.Application:write"
            ],
            "env": {
                "MERGE_API_KEY": "your_api_key",
                "MERGE_ACCOUNT_TOKEN": "your_account_token"
            }
        }
    }
}

作用域格式: '<category>.<CommonModel>:<permission>'
- '<category>': Merge API 类别 (例如: 'hris', 'ats', 'accounting')。
- '<CommonModel>': Merge Common Model 名称 (例如: 'Employee', 'Candidate', 'Account')。
- '<permission>': 权限 ('read' 或 'write'，可选，不指定则授予所有权限)。
示例作用域:
- 'hris.Employee:read': 允许读取 HRIS 类别的员工数据。
- 'ats.Candidate:write': 允许在 ATS 类别中创建或更新候选人数据。
- 'accounting.Account': 允许对 Accounting 类别的账户数据执行所有操作。
默认作用域: 如果不指定作用域，服务器将启用所有可用的作用域 (取决于您的 Merge API 账户配置和 Linked Account 权限)。

基本使用方法

确保已按照安装步骤配置 MCP 客户端。
启动 MCP 服务器 (通常客户端会自动启动，或者根据客户端的指示手动启动)。
在 MCP 客户端中，选择配置中定义的服务器名称 ('"merge-mcp-server"' 或您自定义的名称)。
现在您可以开始使用自然语言与 Merge API 数据进行交互了。例如，在 Claude Desktop 中，您可以提问类似 "Show me a list of employees" 或 "Create a new job application"。

运行服务器

在终端中执行以下命令即可启动服务器 (通常在配置客户端后无需手动运行，客户端会自动启动):

uvx merge-mcp

或者如果 'uvx' 不可用，尝试使用 Python 直接运行 (可能需要先切换到项目 src 目录)：

python -m merge_mcp.main

确保 'MERGE_API_KEY' 和 'MERGE_ACCOUNT_TOKEN' 环境变量已正确设置。

关键词

项目简介

主要功能点

安装步骤

基本使用方法

运行服务器

信息