Planhat MCP
This server exposes 60 Planhat MCP tools that let an AI assistant read and update customer data across 12 Planhat resource types using list/get/create/update/delete operations.
Companies: customer accounts, with search and extra-field support
Contacts: end users at customer accounts
Opportunities: sales and expansion deals
Notes: logged notes on accounts
Conversations: all logged touchpoints, including emails, calls, notes, and tickets
Users: your team members in Planhat
Assets: products or objects tied to a customer
Issues: bugs and feature requests
Tickets: support tickets, filterable by company, status, or search
Tasks: to-dos and scheduled activities
Licenses: recurring revenue records
Invoices: billing records
Safety controls: read-only mode, disable-delete mode, and per-tool MCP read-only/destructive hints
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Planhat MCP show me companies with upcoming renewals"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Double-click the downloaded file. Claude Desktop opens an install pop-up.
Review the pop-up and click Install.
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.
Paste the token into the token field. It is stored in your system keychain, never in a file on disk.
Optional: tick Read-only mode or Disable delete tools to limit what the AI can do.
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.sha256Switching from a manual install? Remove the old
planhatentry fromclaude_desktop_config.jsonfirst, 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 build2. Add your Planhat token:
cp .env.example .env
open .env # paste your token after PLANHAT_TOKEN= and saveThe 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 |
| Only the list/get tools exist; nothing in Planhat can be changed. |
| 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 tagsThe 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 |
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. |
| The token is wrong, expired, or was rotated. Paste a fresh one. |
| Bundle installs: re-open the extension's settings and fill in the token. Manual installs: there is no |
| Install Node.js 18 or newer, or point |
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 stdioBuild 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 toolscreate_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_assetCDestructiveIdempotent
Delete a Planhat asset.
Inputs: asset_id (required).
delete_companyCDestructiveIdempotent
Delete a Planhat company.
Inputs: company_id (required).
delete_contactBDestructiveIdempotent
Delete a Planhat contact (end-user).
Inputs: contact_id (required).
delete_conversationCDestructiveIdempotent
Delete a Planhat conversation.
Inputs: conversation_id (required).
delete_invoiceCDestructiveIdempotent
Delete a Planhat invoice.
Inputs: invoice_id (required).
delete_issueBDestructiveIdempotent
Delete a Planhat issue.
Inputs: issue_id (required).
delete_licenseBDestructiveIdempotent
Delete a Planhat license.
Inputs: license_id (required).
delete_noteCDestructiveIdempotent
Delete a Planhat note.
Inputs: note_id (required).
delete_opportunityBDestructiveIdempotent
Delete a Planhat opportunity.
Inputs: opportunity_id (required).
delete_taskCDestructiveIdempotent
Delete a Planhat task.
Inputs: task_id (required).
delete_ticketADestructiveIdempotent
Delete a Planhat ticket.
Inputs: ticket_id (required).
delete_userCDestructiveIdempotent
Delete a Planhat user (team member).
Inputs: user_id (required).
get_assetARead-only
Get a Planhat asset by ID.
Inputs: asset_id (required).
get_companyARead-only
Get a Planhat company by ID.
Inputs: company_id (required).
get_contactARead-only
Get a Planhat contact (end-user) by ID.
Inputs: contact_id (required).
get_conversationCRead-only
Get a Planhat conversation by ID.
Inputs: conversation_id (required).
get_invoiceARead-only
Get a Planhat invoice by ID.
Inputs: invoice_id (required).
get_issueBRead-only
Get a Planhat issue by ID.
Inputs: issue_id (required).
get_licenseARead-only
Get a Planhat license by ID.
Inputs: license_id (required).
get_noteCRead-only
Get a Planhat note by ID.
Inputs: note_id (required).
get_opportunityBRead-only
Get a Planhat opportunity by ID.
Inputs: opportunity_id (required).
get_taskARead-only
Get a Planhat task by ID.
Inputs: task_id (required).
get_ticketCRead-only
Get a Planhat ticket by ID.
Inputs: ticket_id (required).
get_userBRead-only
Get a Planhat user by ID.
Inputs: user_id (required).
list_assetsCRead-only
List Planhat assets.
Inputs: limit, offset, company_id.
list_companiesBRead-only
List or search Planhat companies.
Inputs: limit, offset, search.
list_contactsARead-only
List Planhat contacts, optionally filtered by company.
Inputs: limit, offset, company_id.
list_conversationsARead-only
List Planhat conversations of any type, optionally filtered by type (e.g. 'email', 'note', 'ticket').
Inputs: type, limit, offset, company_id.
list_invoicesCRead-only
List Planhat invoices.
Inputs: limit, offset, company_id.
list_issuesCRead-only
List Planhat issues (bugs / feature requests).
Inputs: limit, offset, company_id.
list_licensesCRead-only
List Planhat licenses (recurring revenue records).
Inputs: limit, offset, company_id.
list_notesCRead-only
List Planhat notes.
Inputs: limit, offset, company_id.
list_opportunitiesCRead-only
List Planhat opportunities.
Inputs: limit, offset, company_id.
list_tasksCRead-only
List Planhat tasks.
Inputs: limit, offset, company_id, is_archived.
list_ticketsBRead-only
List Planhat tickets, optionally filtered by company, status, or a search term.
Inputs: limit, offset, search, status, +1 more.
list_usersBRead-only
List Planhat users (team members).
Inputs: limit, offset.
update_assetCDestructiveIdempotent
Update fields on an existing Planhat asset.
Inputs: asset_id (required), name, extra_fields.
update_companyADestructiveIdempotent
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_contactCDestructiveIdempotent
Update fields on an existing Planhat contact (end-user).
Inputs: contact_id (required), email, last_name, first_name, +1 more.
update_conversationBDestructiveIdempotent
Update fields on an existing Planhat conversation.
Inputs: conversation_id (required), subject, description, extra_fields.
update_invoiceBDestructiveIdempotent
Update fields on an existing Planhat invoice.
Inputs: invoice_id (required), extra_fields.
update_issueCDestructiveIdempotent
Update fields on an existing Planhat issue.
Inputs: issue_id (required), title, extra_fields.
update_licenseBDestructiveIdempotent
Update fields on an existing Planhat license.
Inputs: license_id (required), value, extra_fields.
update_noteCDestructiveIdempotent
Update fields on an existing Planhat note.
Inputs: note_id (required), text, extra_fields.
update_opportunityBDestructiveIdempotent
Update fields on an existing Planhat opportunity.
Inputs: opportunity_id (required), title, status, close_date, +1 more.
update_taskCDestructiveIdempotent
Update fields on an existing Planhat task.
Inputs: task_id (required), action, status, extra_fields.
update_ticketCDestructiveIdempotent
Update fields on an existing Planhat ticket.
Inputs: ticket_id (required), status, subject, description, +1 more.
update_userCDestructiveIdempotent
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
Scored across 60 tools
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.
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.
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.
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
Related MCP Connectors
Operate the Plixana CRM from any AI: contacts, deals, quotes, WhatsApp and metrics.
Ask your customer portal and CRM anything, in plain English
Search, summarize, and update your RevOrbit CRM (leads, deals, contacts, tasks) in plain language.
Streamline your Attio workflows using natural language to search, create, update, and organize com…
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceTalk to your SaaS tools including HubSpot, Salesforce, and more61 npm50MIT
- FlicenseBqualityBmaintenanceProvides access to Vitally customer success platform data, enabling users to search accounts and users, view health scores, manage conversations and tasks, and create notes through natural language interactions.112-
- AlicenseBqualityDmaintenanceEnables interaction with Plane.so project management API through natural language, allowing users to manage issues, cycles, and projects.10MIT
- AlicenseNot gradedqualityCmaintenanceConnects Twenty CRM with AI assistants like Claude, enabling natural language interactions with customer data. Supports CRUD operations for people, companies, tasks, notes, and advanced search.108MIT