使用说明

呼吸HR MCP服务器

将Breathe HR数据连接到AI助手 --通过自然语言查询访问员工、缺勤、休假请求和公司信息，具有安全的读写功能。

🚨 免责声明：此项目由创建模糊实验室具有良好的氛围，未得到Breathe HR的正式支持。请自行决定使用。

这有什么作用

通过向人工智能助手提出自然语言问题，改变您处理Breathe HR数据的方式，例如：

“显示工程部的所有员工”
“本月谁有未处理的休假申请？”
“为John Doe创建3月1日至5日的假期申请”
“搜索名为Sarah的员工”
“我们目前各部门的员工人数是多少？”

🔐 安全访问 -具有受控权限的API密钥身份验证
🚀 即时设置 --可与任何兼容MCP的AI助手配合使用
📊 全覆盖 --访问员工、缺勤、部门等信息

快速开始

1.获取呼吸HR API密钥

登录您的Breathe HR帐户
首选 设置→ 集成→ API
创建一个新的API密钥并复制它

2.安装和配置

macOS设置

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and install
git clone https://github.com/fuzzylabs/breathehr-mcp.git
cd breathehr-mcp
uv sync

Linux/Windows安装程序

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh  # Linux/macOS
# OR for Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Clone and install
git clone https://github.com/fuzzylabs/breathehr-mcp.git
cd breathehr-mcp
uv sync

3.连接到您的AI助手

克劳德桌面

将此添加到您的Claude Desktop配置文件中：

配置位置：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "breathe-hr": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/breathehr-mcp",
        "python",
        "-m",
        "breathe_hr_mcp"
      ],
      "env": {
        "BREATHE_HR_API_KEY": "your_breathe_hr_api_key_here"
      }
    }
  }
}

光标

📋 快速设置：

复制此Cursor深度链接并将其粘贴到浏览器地址栏中：

cursor://anysphere.cursor-deeplink/mcp/install?name=breathe-hr&config=eyJicmVhdGhlLWhyIjp7ImNvbW1hbmQiOiJ1diIsImFyZ3MiOlsicnVuIiwiLS1kaXJlY3RvcnkiLCIvcGF0aC90by95b3VyL2JyZWF0aGVoci1tY3AiLCJweXRob24iLCItbSIsImJyZWF0aGVfaHJfbWNwIl0sImVudiI6eyJCUkVBVEhFX0hSX0FQSV9LRVkiOiJ5b3VyX2JyZWF0aGVfaHJfYXBpX2tleV9oZXJlIn19fQ==

**💡 How to use:**
1. Copy the entire `cursor://` URL above
2. Paste it into your browser's address bar 
3. Press Enter - this will open Cursor and prompt to install the MCP server

**Note:** After clicking the button, you'll need to:
1. Update the path `/path/to/your/breathehr-mcp` to your actual installation directory
2. Replace `your_breathe_hr_api_key_here` with your actual Breathe HR API key

Or manually add this to your Cursor MCP settings:

```json
{
  "breathe-hr": {
    "command": "uv",
    "args": [
      "run",
      "--directory",
      "/path/to/your/breathehr-mcp",
      "python",
      "-m",
      "breathe_hr_mcp"
    ],
    "env": {
      "BREATHE_HR_API_KEY": "your_breathe_hr_api_key_here"
    }
  }
}

其他MCP客户端

此服务器与任何MCP客户端兼容。有关MCP服务器配置，请参阅客户的文档。

💡 安装帮助：

使用紫外线（推荐）： 使用 uv run 命令如上所示-不需要Python路径！
Claude Desktop的紫外线路径： 使用完整路径 ~/.local/bin/uv （找到你的 which uv)
手动Python路径（如果不使用uv）：
- macOS（Homebrew）： /opt/homebrew/bin/python3 （苹果硅）或 /usr/local/bin/python3 （英特尔）
- macOS（系统）： /usr/bin/python3 （如果可用）
- 找到你的Python： 跑 which python3 在终端
- 窗户： 尝试 C:\Python311\python.exe

4.开始使用

重启你的AI助手
开始提问！

尝试以下示例查询：

“列出我的Breathe HR员工”
“显示待处理的休假请求”
“为员工123创建假期申请”
“在工程部门寻找员工”

您可以访问的内容

此MCP服务器提供 安全访问 您的Breathe HR数据：

数据类型	你能做什么
👥 员工	列表、搜索、查看详细信息、按部门/状态筛选
🏖️ 缺勤	查看休假记录，按日期/类型筛选，创建请求
🏢 公司	访问帐户信息和设置
📋 部门	列出组织结构和团队

可用工具：

list_employees -使用筛选器获取分页员工列表
get_employee -获取详细的员工信息
search_employees -按查询搜索员工
list_absences -通过筛选获取缺勤记录
create_leave_request -提交新的休假申请
get_employee_absences -获取特定员工的缺勤情况
get_account_info -获取公司帐户详细信息
get_departments -列出所有部门

故障排除

常见问题

“没有名为'breathe_hr_mcp'的模块”

使用紫外线： 确保您使用的是绝对目录路径 uv run --directory
手动设置： 验证Python可以找到已安装的包： pip list | grep fastmcp

“spawn uv ENOENT”或“找不到命令：uv”

先安装uv： curl -LsSf https://astral.sh/uv/install.sh | sh
安装后重新启动终端
验证安装： uv --version

“生成python ENOENT”（如果不使用uv）

切换到uv设置（推荐）或在配置中使用完整的Python路径
检查你的Python路径： which python3
尝试不同的常见路径： /usr/bin/python3, /usr/local/bin/python3, /opt/homebrew/bin/python3

“身份验证失败”

验证您的Breathe HR API键是否正确
检查密钥在Breathe HR中是否具有适当的权限
确保键周围没有多余的空格或引号

“超出费率限制”

呼吸HR有API速率限制
请等待几分钟，然后重试
减少请求的频率

MCP工具未显示在您的AI助手中

配置更改后重新启动AI助手
检查配置文件语法是否为有效的JSON
验证文件路径是绝对的，而不是相对的

获取帮助

问题和Bug： GitHub问题
呼吸HR API文件： 开发者.breathehr.com
MCP协议： 模型上下文协议.io

渲染部署（安全远程HTTP访问）

想要远程部署MCP服务器，以便多个用户可以通过HTTP访问它吗？部署到渲染，使用API密钥身份验证轻松进行云托管。

快速部署

手动部署

分叉此存储库 转到您的GitHub帐户
创建渲染帐户 在 render.com
创建新的Web服务 并连接您的GitHub分支
配置服务：
- 构建命令： pip install uv && uv sync
- 启动命令： uv run uvicorn breathe_hr_mcp:app --host 0.0.0.0 --port $PORT
- 计划： 免费（或选择付费计划以获得更好的性能）
设置环境变量 在渲染仪表板中：
- BREATHE_HR_API_KEY：呼吸HR API键
- MCP_API_KEY：用于身份验证的安全随机API密钥（请参阅下面的生成说明）
部署 -Render将自动构建和部署您的服务

生成安全的API密钥

为生成安全随机API密钥 MCP_API_KEY 环境变量：

# Using Python
python -c "import secrets; print(secrets.token_urlsafe(32))"

# Using OpenSSL  
openssl rand -base64 32

# Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

⚠️ 重要：安全存储此API密钥-您需要它来配置MCP客户端。

使用已部署的服务器

部署后，您将获得一个URL，如下所示 https://your-service.onrender.com。配置您的MCP客户端以使用：

克劳德桌面：

{
  "mcpServers": {
    "breathe-hr": {
      "command": "curl",
      "args": [
        "-X", "POST",
        "https://your-service.onrender.com/mcp/",
        "-H", "Content-Type: application/json",
        "-H", "Authorization: Bearer YOUR_MCP_API_KEY_HERE",
        "-d", "@-"
      ]
    }
  }
}

替换 YOUR_MCP_API_KEY_HERE 使用您在“渲染”中生成和设置的API键。

🔒 安全说明：只有当 MCP_API_KEY 设置环境变量。如果没有配置API密钥，服务器将接受未经验证的请求（对本地开发有用）。

直接HTTP访问：

# List available tools
curl -X POST https://your-service.onrender.com/mcp/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_MCP_API_KEY_HERE" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

# List employees
curl -X POST https://your-service.onrender.com/mcp/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_MCP_API_KEY_HERE" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "list_employees",
      "arguments": {"page": 1, "per_page": 10}
    },
    "id": 1
  }'

⚠️ 关于免费等级的说明： Render的免费层在不活动后会关闭服务。首次请求可能需要30-60秒才能唤醒服务。

对于开发者

开发设置

环境变量（用于开发）：

cp .env.example .env
# Edit .env and set BREATHE_HR_API_KEY=your_api_key_here

运行测试：

uv run pytest

HTTP服务器（用于测试）：

uv run uvicorn breathe_hr_mcp:app --reload
# Server available at http://localhost:8000/mcp/

API测试

测试架构终结点：

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

测试上市员工：

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "list_employees",
      "arguments": {"page": 1, "per_page": 10}
    },
    "id": 1
  }'

建筑

服务器： 带FastAPI后端的FastMCP框架
协议： 通过stdio实现模型上下文协议（MCP）
API 通过安全访问呼吸HR API v1
身份验证： 承载令牌（API密钥）