个人mcp服务器
用于与Personio HR API集成的模型上下文协议（MCP）服务器。该服务器提供了通过Claude或其他支持MCP协议的AI助手访问员工数据、考勤记录、缺勤信息和分析的工具。
特性
- 员工管理：获取员工详细信息，列出所有员工，搜索员工，按办公室/地点筛选
- 数据导出：以JSON或CSV格式导出员工列表，以便轻松集成电子表格
- 考勤跟踪：检索考勤记录，检查当前考勤状态
- 缺勤管理：查看缺勤、检查缺勤余额、获取缺勤类型
- 分析：生成考勤报告，检查团队可用性，分析缺勤统计数据
- 公用事业：API健康检查
先决条件
- Node.js 18或更高版本
- Personio API凭据（客户端ID和客户端机密）
安装
快速安装（推荐给GoMedicus团队）
通过npm全局安装包：
npm install -g @gomedicus/personio-mcp-server然后运行安装向导：
personio-mcp-setup安装向导将：
- 询问您的Personio API证书
- 自动配置克劳德桌面
- 验证安装
就是这样！ 重新启动Claude Desktop，Personio工具将可用。
______________________________________________________________________
手动安装（开发）
对于开发或手动设置：
- 克隆此仓库
- 安装依赖项：
npm install- 构建项目：
npm run build配置
环境变量
设置以下环境变量：
PERSONIO_CLIENT_ID：您的Personio API客户端IDPERSONIO_CLIENT_SECRET：您的Personio API客户机密
您可以在 .env 项目根目录中的文件：
PERSONIO_CLIENT_ID=your_client_id
PERSONIO_CLIENT_SECRET=your_client_secretMCP客户端配置（克劳德桌面）
要将此服务器与Claude Desktop一起使用，请将其添加到您的Claude配置文件中：
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%/Claude/claude_desktop_config.json
添加以下配置：
{
"mcpServers": {
"personio": {
"command": "node",
"args": [
"/absolute/path/to/personio-server/build/index.js"
],
"env": {
"PERSONIO_CLIENT_ID": "your_client_id",
"PERSONIO_CLIENT_SECRET": "your_client_secret"
}
}
}
}重要提示： 替换 /absolute/path/to/personio-server 带有此项目目录的实际路径。
添加配置后：
- 重新启动克劳德桌面
- Personio工具将在您的对话中可用
- 现在，您可以要求Claude导出包含位置的员工列表！
用法
运行服务器
npm start或者使用环境变量：
PERSONIO_CLIENT_ID=your_client_id PERSONIO_CLIENT_SECRET=your_client_secret npm start与克劳德一起使用
配置后，您可以要求Claude使用Personio工具。以下是一些示例请求：
带地点的出口员工：
"Please export all employees from the Hamburg office as CSV"
"Give me a list of all employees with their office locations"
"Export the first 50 employees to CSV format"按位置筛选：
"How many employees work in the Berlin office?"
"Show me all employees in the Rangendingen location"
"List employees from remote offices"获取员工信息：
"Get details for employee ID 12345"
"Search for employees named John"
"Show me all employees in the IT department"Claude将使用适当的Personio MCP工具来满足您的请求，并可以根据需要以JSON或CSV格式导出数据。
可用工具
员工工具
get_employee：通过ID获取特定员工的详细信息
- 返回：id、姓名、电子邮件、职位、部门、， 办公室/地点、状态、雇佣日期、每周小时数、鞋尺寸
list_employees：使用可选的过滤和导出格式获取所有员工的列表
- 参数： - limit：返回的最大员工数（默认值：200） - offset：分页时跳过的员工数量 - attributes：要检索的特定员工属性 - office：按办公室/工作场所名称筛选员工（不区分大小写的部分匹配） - format：输出格式- "json" （默认）或 "csv" 用于电子表格导出 - 特征： - 按办公室/地点筛选，以查找特定工作场所的员工 - 导出为CSV格式，便于导入电子表格 - 在所有员工记录中包括办公室/位置字段
search_employees：按姓名、电子邮件或部门搜索员工
示例用法：
// Get all employees in Hamburg office
list_employees({ office: "Hamburg" })
// Export first 100 employees as CSV
list_employees({ limit: 100, format: "csv" })
// Get employees from a specific office as CSV
list_employees({ office: "Berlin", format: "csv" })考勤工具（V1 API）
get_attendance_records：使用可选日期和员工筛选器检索考勤记录get_current_attendance_status：获取今天的当前出勤状态generate_attendance_report：为日期范围生成考勤分析报告
考勤工具（V2 API）-增强功能
get_attendance_periods_v2：列出考勤时段，支持时区和增强过滤get_attendance_period_v2：通过ID获取特定的出勤期create_attendance_period_v2：使用时区支持和时段类型创建考勤时段update_attendance_period_v2：更新现有考勤周期delete_attendance_period_v2：删除考勤时段generate_v1_v2_compatibility_report：比较迁移规划的v1和v2 API响应
V2 API功能：
- 时区支持（带时区信息的开始/结束时间）
- 支持不同时段类型（出勤时段、休息时段）
- ISO 8601日期时间格式支持
- 通过特定范围的消息增强错误处理
- v1/v2数据转换的向后兼容性助手
缺勤工具
get_absences：使用可选筛选器检索缺勤/休假记录get_employee_absence_balance：获取特定员工的缺勤余额get_absence_types：获取所有可用的缺勤/休假类型get_team_absence_overview：获取今天或特定日期范围内谁外出的概述get_absence_statistics：获取缺勤统计数据和趋势
实用工具
api_health_check：检查Personio API连接和身份验证状态
发展
项目结构
src/api/：Personio的API客户端src/auth/：身份验证逻辑src/handlers/：按类别组织的工具处理程序src/validators/：输入验证助手src/tools/：工具定义src/index.ts：主服务器文件
建筑
npm run build测试
npm test测试位置导出功能
运行位置导出测试脚本以验证新功能：
node test-location-export.mjs这将测试：
- 员工办公室/位置字段检索
- 按办公室筛选员工
- CSV导出格式
- 将办公室过滤与CSV导出相结合
CSV导出格式
使用时 format: "csv" 随着 list_employees 工具，输出包括：
- 带列名的标题行
- 带字段的员工数据：ID、姓名、电子邮件、职位、部门、办公室、状态、雇佣日期、每周工作时间
- 特殊字符（逗号、引号、换行符）的正确CSV转义
- 元数据，包括导出时间戳和员工总数
- 备注：其他字段（如shoe_size）仅以JSON格式可用，不支持CSV导出
CSV格式非常适合：
- 导入Excel或Google表格
- 进一步的数据分析
- 创建报告
- 备份目的
许可证
麻省理工学院
作者
尼古拉·博克霍尔特