Skip to main content
Glama
Planhat MCP

Planhat MCP

NOTE

When hosted connector OAuth or custom connector setup gets in the way, Planhat MCP gives you a direct local connection using a standard API token. Nothing to host and no third-party service between your AI and customer data.

See it in action

You: "Which companies have licenses renewing this quarter?"

Claude: Queries Planhat through the local MCP server and returns the matching companies with their renewal details.

Ask Claude to list records, inspect customer context, create follow-up tasks, or update Planhat directly from the conversation.

Install in Claude Desktop

Download one file, double-click it, paste your token. No terminal, no config files, no code, and nothing to install first.

  1. Download the .mcpb file.

  2. Double-click the downloaded file. Claude Desktop opens an install pop-up.

  3. Review the pop-up and click Install.

  4. Create a Planhat API token if you don't have one: in Planhat, go to Settings > Service Accounts (Private Apps) > API Access Token. Admin access is required.

  5. Paste the token into the token field. It is stored in your system keychain, never in a file on disk.

  6. Optional: tick Read-only mode or Disable delete tools to limit what the AI can do.

  7. Ask Claude: "List my top 3 Planhat companies." An answer means you are done.

If double-clicking does not open Claude Desktop, use Settings > Extensions > Advanced settings > Install Extension and select the downloaded file.

Each release also includes planhat-mcp.mcpb.sha256. To verify a download on macOS or Linux, place both files in the same directory and run:

shasum -a 256 -c planhat-mcp.mcpb.sha256

Switching from a manual install? Remove the old planhat entry from claude_desktop_config.json first, or you'll see two copies of every tool.

Related MCP server: Vitally MCP Server

Manual install

For MCP clients other than Claude Desktop, or if you prefer running from a checkout. Requires Node.js 18 or newer.

1. Get the code and build the server:

git clone https://github.com/da-troll/Planhat-MCP.git ~/planhat-mcp
cd ~/planhat-mcp
npm install
npm run build

2. Add your Planhat token:

cp .env.example .env
open .env        # paste your token after PLANHAT_TOKEN= and save

The token stays in that one file on your machine. Treat it like a password.

3. Register the server in your client's MCP config (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json), replacing YOUR-USERNAME:

{
  "mcpServers": {
    "planhat": {
      "command": "node",
      "args": ["/Users/YOUR-USERNAME/planhat-mcp/dist/server.js"]
    }
  }
}

Restart the client and test with the same question as above.

What Claude can do with it

60 tools across 12 Planhat resource types. Every resource supports the same five verbs: list, get, create, update, delete.

Resource

What it is

Companies

Your customer accounts

Contacts (end users)

People at those customers

Opportunities

Sales/expansion deals

Notes

Logged notes on an account

Conversations

All logged touchpoints: emails, calls, notes, tickets

Users

Your own team members in Planhat

Assets

Products/objects tied to a customer

Issues

Bugs and feature requests

Tickets

Support tickets

Tasks

To-dos and scheduled activities

Licenses

Recurring revenue records

Invoices

Billing records

Claude only ever does what you ask, and the token you create controls what it can touch. A read-only token makes the whole connector read-only.

Optional hardening

Two switches cap what any connected AI can ever do, no matter what it's asked. Bundle installs get them as checkboxes in the install pop-up; manual installs add either to the .env file:

Setting

Effect

PLANHAT_READ_ONLY=1

Only the list/get tools exist; nothing in Planhat can be changed.

PLANHAT_DISABLE_DELETE=1

Everything works except deleting records.

Every tool also carries the standard MCP annotations (readOnlyHint, destructiveHint), so clients that calibrate their permission prompts per tool (asking before destructive calls, auto-approving reads) get the right signals. Whether and when to prompt is always the client's decision; the switches above and the permissions on the Planhat token itself (see SECURITY.md) are the hard limits.

Repository layout

planhat-mcp/
├── README.md                  ← you are here
├── manifest.json              ← .mcpb bundle definition (one-click install)
├── package.json               ← dependencies, scripts, version
├── package-lock.json          ← pinned dependency versions
├── tsconfig.json              ← TypeScript config
├── .env.example               ← token template for manual installs
├── .mcpbignore                ← what stays out of the bundle
├── src/
│   ├── index.ts               ← entry point: load config, serve over stdio
│   ├── server.ts              ← registers tools, applies gates + annotations
│   ├── tools.ts               ← all 60 tool definitions
│   ├── http.ts                ← Planhat REST client
│   └── env.ts                 ← .env loader for manual installs
├── tests/
│   ├── tools.test.ts          ← offline tests for all 60 tools
│   └── http.test.ts           ← HTTP layer: timeout, errors, delete cases
├── AGENTS.md                  ← handbook for AI coding agents
├── CLAUDE.md → AGENTS.md      ← same file, Claude's preferred name
├── LICENSE                    ← MIT
├── CHANGELOG.md               ← release history
├── SECURITY.md                ← token handling & reporting issues
├── CONTRIBUTING.md            ← how to add tools or fix bugs
└── .github/workflows/
    ├── ci.yml                 ← typecheck + tests + bundle gate on every push
    └── release.yml            ← GitHub release with .mcpb asset on version tags

The shipped bundle contains just five files: manifest.json, dist/server.js (one dependency-free build), assets/icon.png, LICENSE and README.md.

Troubleshooting

Symptom

Likely cause & fix

Double-clicking the .mcpb does nothing, or Install is greyed out

Update to a recent Claude Desktop; older builds predate one-click .mcpb extensions. You can also install from Settings > Extensions > Advanced > Install Extension.

Every Planhat tool appears twice

The bundle and an old manual config entry are both installed. Remove mcpServers.planhat from claude_desktop_config.json.

Claude says it has no Planhat tools

Claude Desktop only reads its config on launch. Quit it fully, reopen, and check the JSON has no trailing commas.

HTTP 401 Unauthorized in a tool result

The token is wrong, expired, or was rotated. Paste a fresh one.

PLANHAT_TOKEN is not set

Bundle installs: re-open the extension's settings and fill in the token. Manual installs: there is no .env beside the server, so repeat manual step 2.

command not found: node (manual install)

Install Node.js 18 or newer, or point command at the full path to your node binary.

Tool works but returns []

Usually not an error: that Planhat resource is genuinely empty for your filters.

For engineers

npm install          # install dependencies
npm test             # offline test suite (never touches the live API)
npm run typecheck    # TypeScript type checking
npm run build        # produce dist/server.js
npm start            # run the built server over stdio

Build the one-click bundle locally with npm run build && npx -y @anthropic-ai/mcpb@2.1.2 pack . planhat.mcpb.

Architecture notes, API quirks, and contribution rules live in AGENTS.md and CONTRIBUTING.md. Endpoint paths were verified against the live Planhat API in July 2026. Notably, Planhat has no /notes or /activities REST endpoints; notes and tickets are /conversations under the hood (see AGENTS.md for the full story).

License

MIT. Do what you like, no warranty.

Available Tools

60 tools
create_assetC

Create a new asset in Planhat.

Inputs: name (required), company_id (required), external_id, extra_fields.

create_companyC

Create a new company in Planhat.

Inputs: name (required), owner_id, external_id, extra_fields.

create_contactC

Create a new contact (end-user) in Planhat.

Inputs: email (required), last_name (required), company_id (required), first_name (required), +1 more.

create_conversationC

Create a new conversation in Planhat.

Inputs: company_id (required), type, subject, owner_id, +2 more.

create_invoiceC

Create a new invoice in Planhat.

Inputs: currency (required), company_id (required), invoice_date (required), extra_fields.

create_issueC

Create a new issue in Planhat.

Inputs: title (required), company_id, extra_fields.

create_licenseC

Create a new license in Planhat.

Inputs: value (required), currency (required), company_id (required), extra_fields.

create_noteC

Create a new note in Planhat.

Inputs: text (required), company_id (required), owner_id, contact_id.

create_opportunityC

Create a new opportunity in Planhat.

Inputs: title (required), company_id (required), value, status, +1 more.

create_taskC

Create a new task in Planhat.

Inputs: company_id (required), action, owner_id, main_type, +2 more.

create_ticketC

Create a new ticket in Planhat.

Inputs: company_id (required), subject, owner_id, description, +1 more.

create_userC

Create a new user (team member) in Planhat.

Inputs: email (required), last_name (required), first_name (required), role.

delete_assetC
DestructiveIdempotent

Delete a Planhat asset.

Inputs: asset_id (required).

delete_companyC
DestructiveIdempotent

Delete a Planhat company.

Inputs: company_id (required).

delete_contactB
DestructiveIdempotent

Delete a Planhat contact (end-user).

Inputs: contact_id (required).

delete_conversationC
DestructiveIdempotent

Delete a Planhat conversation.

Inputs: conversation_id (required).

delete_invoiceC
DestructiveIdempotent

Delete a Planhat invoice.

Inputs: invoice_id (required).

delete_issueB
DestructiveIdempotent

Delete a Planhat issue.

Inputs: issue_id (required).

delete_licenseB
DestructiveIdempotent

Delete a Planhat license.

Inputs: license_id (required).

delete_noteC
DestructiveIdempotent

Delete a Planhat note.

Inputs: note_id (required).

delete_opportunityB
DestructiveIdempotent

Delete a Planhat opportunity.

Inputs: opportunity_id (required).

delete_taskC
DestructiveIdempotent

Delete a Planhat task.

Inputs: task_id (required).

delete_ticketA
DestructiveIdempotent

Delete a Planhat ticket.

Inputs: ticket_id (required).

delete_userC
DestructiveIdempotent

Delete a Planhat user (team member).

Inputs: user_id (required).

get_assetA
Read-only

Get a Planhat asset by ID.

Inputs: asset_id (required).

get_companyA
Read-only

Get a Planhat company by ID.

Inputs: company_id (required).

get_contactA
Read-only

Get a Planhat contact (end-user) by ID.

Inputs: contact_id (required).

get_conversationC
Read-only

Get a Planhat conversation by ID.

Inputs: conversation_id (required).

get_invoiceA
Read-only

Get a Planhat invoice by ID.

Inputs: invoice_id (required).

get_issueB
Read-only

Get a Planhat issue by ID.

Inputs: issue_id (required).

get_licenseA
Read-only

Get a Planhat license by ID.

Inputs: license_id (required).

get_noteC
Read-only

Get a Planhat note by ID.

Inputs: note_id (required).

get_opportunityB
Read-only

Get a Planhat opportunity by ID.

Inputs: opportunity_id (required).

get_taskA
Read-only

Get a Planhat task by ID.

Inputs: task_id (required).

get_ticketC
Read-only

Get a Planhat ticket by ID.

Inputs: ticket_id (required).

get_userB
Read-only

Get a Planhat user by ID.

Inputs: user_id (required).

list_assetsC
Read-only

List Planhat assets.

Inputs: limit, offset, company_id.

list_companiesB
Read-only

List or search Planhat companies.

Inputs: limit, offset, search.

list_contactsA
Read-only

List Planhat contacts, optionally filtered by company.

Inputs: limit, offset, company_id.

list_conversationsA
Read-only

List Planhat conversations of any type, optionally filtered by type (e.g. 'email', 'note', 'ticket').

Inputs: type, limit, offset, company_id.

list_invoicesC
Read-only

List Planhat invoices.

Inputs: limit, offset, company_id.

list_issuesC
Read-only

List Planhat issues (bugs / feature requests).

Inputs: limit, offset, company_id.

list_licensesC
Read-only

List Planhat licenses (recurring revenue records).

Inputs: limit, offset, company_id.

list_notesC
Read-only

List Planhat notes.

Inputs: limit, offset, company_id.

list_opportunitiesC
Read-only

List Planhat opportunities.

Inputs: limit, offset, company_id.

list_tasksC
Read-only

List Planhat tasks.

Inputs: limit, offset, company_id, is_archived.

list_ticketsB
Read-only

List Planhat tickets, optionally filtered by company, status, or a search term.

Inputs: limit, offset, search, status, +1 more.

list_usersB
Read-only

List Planhat users (team members).

Inputs: limit, offset.

update_assetC
DestructiveIdempotent

Update fields on an existing Planhat asset.

Inputs: asset_id (required), name, extra_fields.

update_companyA
DestructiveIdempotent

Update fields on an existing Planhat company. Pass any other Planhat company field via extra_fields.

Inputs: company_id (required), name, owner_id, external_id, +1 more.

update_contactC
DestructiveIdempotent

Update fields on an existing Planhat contact (end-user).

Inputs: contact_id (required), email, last_name, first_name, +1 more.

update_conversationB
DestructiveIdempotent

Update fields on an existing Planhat conversation.

Inputs: conversation_id (required), subject, description, extra_fields.

update_invoiceB
DestructiveIdempotent

Update fields on an existing Planhat invoice.

Inputs: invoice_id (required), extra_fields.

update_issueC
DestructiveIdempotent

Update fields on an existing Planhat issue.

Inputs: issue_id (required), title, extra_fields.

update_licenseB
DestructiveIdempotent

Update fields on an existing Planhat license.

Inputs: license_id (required), value, extra_fields.

update_noteC
DestructiveIdempotent

Update fields on an existing Planhat note.

Inputs: note_id (required), text, extra_fields.

update_opportunityB
DestructiveIdempotent

Update fields on an existing Planhat opportunity.

Inputs: opportunity_id (required), title, status, close_date, +1 more.

update_taskC
DestructiveIdempotent

Update fields on an existing Planhat task.

Inputs: task_id (required), action, status, extra_fields.

update_ticketC
DestructiveIdempotent

Update fields on an existing Planhat ticket.

Inputs: ticket_id (required), status, subject, description, +1 more.

update_userC
DestructiveIdempotent

Update fields on an existing Planhat user (team member).

Inputs: user_id (required), email, last_name, first_name, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 60 tools

    Disambiguation5/5

    Each tool operates on a unique entity type (asset, company, contact, conversation, invoice, issue, license, note, opportunity, task, ticket, user) with a specific action (create, delete, get, list, update), ensuring no overlap or ambiguity.

    Naming Consistency5/5

    All tools follow a strict and predictable verb_noun pattern using snake_case (e.g., create_asset, delete_company, list_tickets), with no deviations or mixed conventions.

    Tool Count4/5

    60 tools is high but directly corresponds to 12 entities × 5 operations (CRUD+L), which is justified for a full-featured CRM tool. Slightly above the typical 3-15 range but appropriately scoped.

    Completeness5/5

    Each entity has complete lifecycle coverage with create, read (get/list), update, and delete operations. Additional filtering capabilities in list functions further enhance coverage without gaps.

    Maintenance

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers