helloHQ

License: MIT TypeScript MCP helloHQ

A Model Context Protocol (MCP) server for helloHQ — the project management & ERP platform by everii.

This server connects AI assistants like Claude to your helloHQ instance, giving them access to projects, documents, time tracking, and more.

Features

Organized by helloHQ module:

72 tools total, covering the helloHQ v2 REST API.

Quick Start

1. Get an API Token

In helloHQ, go to Admin → Settings → API and create an access token:

• User Token — respects the user's permissions (recommended)
• Sync Token — system-wide access without user context

2. Install

From source:

git clone https://github.com/bm1-phillip/hellohq-mcp.git
cd hellohq-mcp
npm install
npm run build

3. Configure your MCP Client

{
  "mcpServers": {
    "hellohq": {
      "command": "node",
      "args": ["/path/to/hellohq-mcp/dist/index.js"],
      "env": {
        "HELLOHQ_API_TOKEN": "your-api-token"
      }
    }
  }
}

claude mcp add hellohq -s user \
  -e HELLOHQ_API_TOKEN=your-api-token \
  -- node /path/to/hellohq-mcp/dist/index.js

Environment Variables

Usage Examples

Once configured, you can ask your AI assistant things like:

"Show me all active projects"

"What tasks are open in project K-25-398?"

"List all invoices from this month"

"Create a reporting: 2 hours on task 12345 for today"

"Start the time tracker on task 54321"

Example: Listing Projects

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"
  }
]

Example: Reading a Document

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"
  }
}

Example: Reporting Time

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
}

Example: Time Tracking

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

Filtering

All list_* tools support OData-style filtering, sorting, and pagination:

# 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"

Common filter operators

API Reference

This server uses the helloHQ API v2 — a standard REST API with token-based authentication.

• Base URL: https://api.hellohq.io/v2
• Rate Limit: 1000 requests/minute
• Documentation: developer.hellohq.io

Project Structure

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

About BM1

hellohq-mcp is built and maintained by BM1, a German agency for SEO, web development and custom software. We build search-visible websites, data-driven SEO setups and special-purpose tooling like this MCP server, which automates our agency back office. If you need help with SEO, a web project or an integration nobody offers off the shelf — talk to us.

License

MIT