helloHQ MCP服务器
   
A. 模型上下文协议（MCP） 服务器 你好HQ --项目管理和ERP平台 从不.
该服务器连接AI助手，如 克劳德 访问您的helloHQ实例，使他们能够访问项目、文档、时间跟踪等。
______________________________________________________________________
特性
| 类别 | 读 | 写 | 工具 |
|---|---|---|---|
| 项目 | ✅ | ✅ | list_projects get_project get_project_members get_project_statuses create_project update_project delete_project |
| 任务 | ✅ | ✅ | list_tasks get_project_tasks get_task_statuses create_task update_task set_task_status mark_task_done mark_task_open |
| 文件 | ✅ | ✅ | list_documents get_document get_document_positions get_document_elements get_document_comments get_document_statuses get_document_templates create_document update_document delete_document change_document_status change_document_template copy_document create_document_from_document add_document_payment add_document_comment |
| 文档位置 | — | ✅ | create_free_text_position create_service_position create_service_set_position create_text_position update_document_position delete_document_position |
| 文档元素 | — | ✅ | create_document_text_element update_document_text_element create_document_page_break create_document_table delete_document_element |
| 报告 | ✅ | ✅ | list_reportings get_reporting create_reporting update_reporting delete_reporting change_reporting_task |
| 工作时间 | ✅ | ✅ | list_working_times create_working_time get_running_working_time start_working_time stop_working_time update_running_working_time |
| 用户 | ✅ | — | list_users get_user |
| 公司 | ✅ | ✅ | list_companies get_company create_company update_company delete_company |
| 联系人 | ✅ | ✅ | list_contact_persons get_contact_person create_contact_person update_contact_person delete_contact_person |
66工具 总计，涵盖helloHQ v2 REST API。
______________________________________________________________________
快速开始
1.获取API代币
在helloHQ中，转到 管理员→ 设置→ API 并创建访问令牌：
- 用户令牌 --尊重用户的权限（推荐）
- 同步令牌 --无需用户上下文的全系统访问
2.安装
来源：
git clone https://github.com/bm1-phillip/hellohq-mcp.git
cd hellohq-mcp
npm install
npm run build3.配置您的MCP客户端
Claude Desktop
编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：
{
"mcpServers": {
"hellohq": {
"command": "node",
"args": ["/path/to/hellohq-mcp/dist/index.js"],
"env": {
"HELLOHQ_API_TOKEN": "your-api-token"
}
}
}
}Claude Code
claude mcp add hellohq -s user \
-e HELLOHQ_API_TOKEN=your-api-token \
-- node /path/to/hellohq-mcp/dist/index.jsOther MCP Clients
任何兼容MCP的客户端都可以使用此服务器。将其配置为 标准 运输：
- 命令：
node - Args：
["/path/to/hellohq-mcp/dist/index.js"] - 环境：
HELLOHQ_API_TOKEN=your-api-token
环境变量
| 变量 | 必填 | 描述 |
|---|---|---|
HELLOHQ_API_TOKEN | ✅ | 来自helloHQ的API访问令牌 |
HELLOHQ_API_URL | - | 自定义API基础URL（默认值： https://api.hellohq.io/v2) |
______________________________________________________________________
使用示例
配置后，您可以向AI助手询问以下问题：
“显示所有活动项目”
“K-25-398项目中有哪些任务是开放的？”
“列出本月的所有发票”
“创建报告：今天在任务12345上花费2小时”
“启动任务54321的时间跟踪器”
示例：列出项目
User: Show me active projects for Acme Corp
Tool call: list_projects
filter: "companyId eq 61037"
expand: "company,projectStatus"
top: 10[
{
"id": 519,
"name": "Website Relaunch (Acme)",
"number": "K-25-398",
"projectStatus": {
"name": "In Progress",
"inProgress": true
},
"company": {
"name": "Acme Corp GmbH"
},
"startDate": "2025-02-01T00:00:00",
"plannedFinishDate": "2026-01-31T00:00:00"
}
]示例：阅读文档
User: Show me quotation AN-26-0126
Tool call: get_document
id: 1963
expand: "company,project,positions,documentStatusEntity"{
"id": 1963,
"documentType": "Quotation",
"number": "AN-26-0126",
"date": "2026-04-02T00:00:00",
"netValue": 892.50,
"taxValue": 169.58,
"grossValue": 1062.08,
"currency": "EUR",
"company": {
"name": "Acme Corp GmbH"
},
"project": {
"name": "Website Relaunch (Acme)",
"number": "K-25-398"
},
"documentStatusEntity": {
"name": "Sent"
}
}示例：报告时间
User: Log 1.5 hours for task "Analytics Setup" today
Tool call: create_reporting
name: "Set up analytics properties and configured events"
startOn: "2026-04-02T12:30:00"
endOn: "2026-04-02T14:00:00"
taskId: 96095
userId: 11009{
"id": 32355,
"name": "Set up analytics properties and configured events",
"startOn": "2026-04-02T12:30:00Z",
"endOn": "2026-04-02T14:00:00Z",
"duration": 1.5,
"chargeRateValue": 85,
"isApproved": false,
"projectId": 41,
"taskId": 96095,
"userId": 11009
}示例：时间跟踪
User: Start the timer on task 97875
Tool call: start_working_time
taskId: 97875
note: "Bug fixes"User: Stop the timer
Tool call: stop_working_time______________________________________________________________________
过滤
全部 list_* 工具支持OData风格的过滤、排序和分页：
# Filter by company
filter: "companyId eq 123"
# Filter by date range
filter: "startOn ge 2025-01-01T00:00:00 and startOn lt 2025-02-01T00:00:00"
# Filter by status
filter: "isDone eq false"
# Sort results
orderby: "date desc"
# Pagination
top: 20
skip: 40
# Expand related entities
expand: "company,project,projectStatus"常用过滤器运算符
| 操作员 | 描述 | 示例 |
|---|---|---|
eq | 等于 | "status eq 'Active'" |
ne | 不等于 | "isDone ne true" |
gt / ge | 大于/或等于 | "date gt 2025-01-01T00:00:00" |
lt / le | 小于/或等于 | "netValue le 1000" |
and / or | 逻辑运算符 | "isDone eq false and projectId eq 10" |
______________________________________________________________________
API 参考
此服务器使用 helloHQ API v2 -具有基于令牌的认证的标准REST API。
- 基本URL:
https://api.hellohq.io/v2 - 费率限制： 1000个请求/分钟
- 文档： developer.hellohq.io
______________________________________________________________________
项目结构
src/
├── index.ts # MCP server entry point
├── api-client.ts # HelloHQ API client
└── tools/
├── projects.ts # Project tools
├── tasks.ts # Task tools
├── documents.ts # Document tools
├── reportings.ts # Reporting tools
├── working-times.ts # Working time tools
├── companies.ts # Company & contact person tools
└── users.ts # User tools______________________________________________________________________
许可证
麻省理工学院