Breathehr MCP

呼吸HR MCP服务器

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

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

这有什么作用

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

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

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

快速开始

1.获取呼吸HR API密钥

1. 登录您的Breathe HR帐户
2. 首选 设置→ 集成→ API
3. 创建一个新的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:

{ "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.开始使用

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

尝试以下示例查询：

> *“列出我的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：** 
- **呼吸HR API文件：** [开发者.breathehr.com](https://developers.breathehr.com)
- **MCP协议：** [模型上下文协议.io](https://modelcontextprotocol.io)

______________________________________________________________________

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

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

### 快速部署

[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/fuzzylabs/breathehr-mcp)

### 手动部署

1. **分叉此存储库** 转到您的GitHub帐户

1. **创建渲染帐户** 在 [render.com](https://render.com)

1. **创建新的Web服务** 并连接您的GitHub分支

1. **配置服务：**

   - **构建命令：** `pip install uv && uv sync`
   - **启动命令：** `uv run uvicorn breathe_hr_mcp:app --host 0.0.0.0 --port $PORT`
   - **计划：** 免费（或选择付费计划以获得更好的性能）

1. **设置环境变量** 在渲染仪表板中：

   - `BREATHE_HR_API_KEY`：呼吸HR API键
   - `MCP_API_KEY`：用于身份验证的安全随机API密钥（请参阅下面的生成说明）

1. **部署** -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密钥）