Headquarter

Headquarter is an open-source, AI-first business and project management tool. It uses a "Ghost" architecture where data is stored locally in human-readable Markdown and JSON files, exposed via the Model Context Protocol (MCP).

Installation

Quick Install (Recommended)

Download the latest binary for your platform from GitHub Releases:

Platform	File
macOS (Apple Silicon)	headquarter-macos-arm64.zip
macOS (Intel)	headquarter-macos-x64.zip
Linux	headquarter-linux-x64.tar.gz
Windows	headquarter-windows-x64.zip

Extract the archive and configure your MCP client (see below).

Install from Source (For Developers)

git clone https://github.com/axeldotdev/headquarter.git
cd headquarter
npm install
npm run build

Configure Your MCP Client

Add the server to your MCP client configuration. For Claude Desktop, edit your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Using the binary (Quick Install):

{
  "mcpServers": {
    "headquarter": {
      "command": "/path/to/headquarter-macos-arm64"
    }
  }
}

Using Node.js (From Source):

{
  "mcpServers": {
    "headquarter": {
      "command": "node",
      "args": ["/path/to/headquarter/dist/index.js"]
    }
  }
}

Replace /path/to/... with the actual path to the binary or cloned repository.

Verify Installation

Restart Claude Desktop (or your MCP client) and the Headquarter tools should be available. You can test by asking Claude to list projects or create a new one.

Development

For debugging, use the MCP Inspector:

npm run inspect

To build binaries locally (requires Bun):

npm run build:bin

🛠 Tech Stack

• Language: Node.js with TypeScript (Strict Mode).
• Architecture: Modular MCP Server + CLI.
• Protocol: MCP SDK 1.25+
• Data Format: Markdown with YAML Frontmatter (via gray-matter) and JSON.
• Validation: Zod for schema definition and runtime type-safety.
• Code Quality:
  • ESLint: Logic & Type checking (The "PHPStan").
  • Prettier: Formatting (The "Pint").
  • Husky: Git hooks for pre-commit linting.

Tools

• [x] list_projects
• [x] get_project(id)
• [x] create_project(name, content)
• [x] update_project(id, name, content)
• [x] delete_project(id)
• [x] list_issues(?project_id)
• [x] get_issue(id)
• [x] create_issue(name, content, status, priority)
• [x] update_issue(id, name, content, status, priority)
• [x] delete_issue(id)
• [x] list_clients
• [x] get_client(id)
• [x] create_client(name, address, website, email, phone)
• [x] update_client(id, name, address, website, email, phone)
• [x] delete_client(id)
• [x] list_contacts(?client_id)
• [x] get_contact(id)
• [x] create_contact(name, email, phone, job_title)
• [x] update_contact(id, name, email, phone, job_title)
• [x] delete_contact(id)
• [x] list_notes
• [x] get_note(id)
• [x] create_note(content)
• [x] update_note(id, content)
• [x] delete_note(id)

🚀 Current Roadmap

• [x] Initial Project structure & Git config.
• [x] Quality tools setup (ESLint, Prettier, Husky).
• [x] Server setup
• [x] Build every tools