AI导哈

项目管理ERP协议服务器

helloHQ MCP服务器是一个连接AI助手与helloHQ项目管理及ERP平台的协议服务器，提供对项目、文档、时间跟踪等功能的访问。

  • by BM1-de
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 bm1-phillip/hellohq-mcp

使用说明

helloHQ MCP服务器

A. 模型上下文协议（MCP） 服务器 你好HQ --项目管理和ERP平台 从不.

该服务器连接AI助手，如 克劳德 访问您的helloHQ实例，使他们能够访问项目、文档、时间跟踪等。

特性

按helloHQ模块组织：

模块 类别 读 写 工具
客户关系管理 公司 ✅ ✅ 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
项目 项目 ✅ ✅ 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_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_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_planned_revenues get_planned_revenue create_planned_revenue update_planned_revenue delete_planned_revenue change_planned_revenue_status
管理员 用户 ✅ — list_users get_user

72工具 总计，涵盖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 build

3.配置您的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.js
Other 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
    ├── planned-revenues.ts # Planned revenue tools
    └── users.ts       # User tools

关于BM1

hellohq-mcp 由以下人员建造和维护 BM1，德国人 搜索引擎优化、网络开发和定制软件代理。我们构建 搜索可见网站、数据驱动的SEO设置和专用工具 就像这个MCP服务器，它自动化了我们的代理后台。如果你需要 帮助搜索引擎优化、网络项目或没有人提供的集成 货架-- 与我们交谈.

许可证

麻省理工学院

相关 MCP