{
  "markdown": "<div align=\"center\">\n  <img src=\"assets/icon.png\" width=\"80\" height=\"80\" alt=\"Planhat MCP Logo\">\n  <h1>Planhat MCP</h1>\n  <p>\n    <a href=\"https://github.com/da-troll/Planhat-MCP/actions/workflows/ci.yml\"><img src=\"https://img.shields.io/github/actions/workflow/status/da-troll/Planhat-MCP/ci.yml?branch=main&amp;style=flat-square&amp;label=CI&amp;color=2ea44f\" alt=\"CI status\"></a>\n    <a href=\"https://github.com/da-troll/Planhat-MCP/releases\"><img src=\"https://img.shields.io/github/v/release/da-troll/Planhat-MCP?style=flat-square&amp;color=5965f2\" alt=\"Latest release\"></a>\n    <a href=\"package.json\"><img src=\"https://img.shields.io/badge/node-18%2B-5965f2?style=flat-square\" alt=\"Node 18 or newer\"></a>\n    <a href=\"https://modelcontextprotocol.io\"><img src=\"https://img.shields.io/badge/MCP-compatible-5965f2?style=flat-square\" alt=\"MCP compatible\"></a>\n    <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-5965f2?style=flat-square\" alt=\"MIT license\"></a>\n  </p>\n  <p><strong>Talk to your Planhat customer data in plain English.</strong></p>\n  <p>A local Model Context Protocol server with 60 tools for reading and updating Planhat from your AI client.</p>\n</div>\n\n> [!NOTE]\n> 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.\n\n### See it in action\n\n> **You:** \"Which companies have licenses renewing this quarter?\"\n>\n> **Claude:** Queries Planhat through the local MCP server and returns the matching companies with their renewal details.\n\nAsk Claude to list records, inspect customer context, create follow-up tasks, or update Planhat directly from the conversation.\n\n## Install in Claude Desktop\n\nDownload one file, double-click it, paste your token. No terminal, no config files, no code, and nothing to install first.\n\n1. [Download the .mcpb file](https://github.com/da-troll/Planhat-MCP/releases/latest/download/planhat-mcp.mcpb).\n2. Double-click the downloaded file. Claude Desktop opens an install pop-up.\n3. Review the pop-up and click **Install**.\n4. 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.\n5. Paste the token into the token field. It is stored in your system keychain, never in a file on disk.\n6. Optional: tick **Read-only mode** or **Disable delete tools** to limit what the AI can do.\n7. Ask Claude: *\"List my top 3 Planhat companies.\"* An answer means you are done.\n\nIf double-clicking does not open Claude Desktop, use **Settings > Extensions > Advanced settings > Install Extension** and select the downloaded file.\n\nEach release also includes `planhat-mcp.mcpb.sha256`. To verify a download on macOS or Linux, place both files in the same directory and run:\n\n```bash\nshasum -a 256 -c planhat-mcp.mcpb.sha256\n```\n\n> **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.\n\n## Manual install\n\nFor MCP clients other than Claude Desktop, or if you prefer running from a checkout. Requires [Node.js](https://nodejs.org) 18 or newer.\n\n**1. Get the code and build the server:**\n\n```bash\ngit clone https://github.com/da-troll/Planhat-MCP.git ~/planhat-mcp\ncd ~/planhat-mcp\nnpm install\nnpm run build\n```\n\n**2. Add your Planhat token:**\n\n```bash\ncp .env.example .env\nopen .env        # paste your token after PLANHAT_TOKEN= and save\n```\n\nThe token stays in that one file on your machine. Treat it like a password.\n\n**3. Register the server** in your client's MCP config (Claude Desktop: `claude_desktop_config.json`; Cursor: `.cursor/mcp.json`), replacing `YOUR-USERNAME`:\n\n```json\n{\n  \"mcpServers\": {\n    \"planhat\": {\n      \"command\": \"node\",\n      \"args\": [\"/Users/YOUR-USERNAME/planhat-mcp/dist/server.js\"]\n    }\n  }\n}\n```\n\nRestart the client and test with the same question as above.\n\n## What Claude can do with it\n\n60 tools across 12 Planhat resource types. Every resource supports the same five verbs: **list**, **get**, **create**, **update**, **delete**.\n\n| Resource | What it is |\n|---|---|\n| Companies | Your customer accounts |\n| Contacts (end users) | People at those customers |\n| Opportunities | Sales/expansion deals |\n| Notes | Logged notes on an account |\n| Conversations | All logged touchpoints: emails, calls, notes, tickets |\n| Users | Your own team members in Planhat |\n| Assets | Products/objects tied to a customer |\n| Issues | Bugs and feature requests |\n| Tickets | Support tickets |\n| Tasks | To-dos and scheduled activities |\n| Licenses | Recurring revenue records |\n| Invoices | Billing records |\n\nClaude 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.\n\n### Optional hardening\n\nTwo 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:\n\n| Setting | Effect |\n|---|---|\n| `PLANHAT_READ_ONLY=1` | Only the list/get tools exist; nothing in Planhat can be changed. |\n| `PLANHAT_DISABLE_DELETE=1` | Everything works except deleting records. |\n\nEvery 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](SECURITY.md)) are the hard limits.\n\n## Repository layout\n\n```\nplanhat-mcp/\n├── README.md                  ← you are here\n├── manifest.json              ← .mcpb bundle definition (one-click install)\n├── package.json               ← dependencies, scripts, version\n├── package-lock.json          ← pinned dependency versions\n├── tsconfig.json              ← TypeScript config\n├── .env.example               ← token template for manual installs\n├── .mcpbignore                ← what stays out of the bundle\n├── src/\n│   ├── index.ts               ← entry point: load config, serve over stdio\n│   ├── server.ts              ← registers tools, applies gates + annotations\n│   ├── tools.ts               ← all 60 tool definitions\n│   ├── http.ts                ← Planhat REST client\n│   └── env.ts                 ← .env loader for manual installs\n├── tests/\n│   ├── tools.test.ts          ← offline tests for all 60 tools\n│   └── http.test.ts           ← HTTP layer: timeout, errors, delete cases\n├── AGENTS.md                  ← handbook for AI coding agents\n├── CLAUDE.md → AGENTS.md      ← same file, Claude's preferred name\n├── LICENSE                    ← MIT\n├── CHANGELOG.md               ← release history\n├── SECURITY.md                ← token handling & reporting issues\n├── CONTRIBUTING.md            ← how to add tools or fix bugs\n└── .github/workflows/\n    ├── ci.yml                 ← typecheck + tests + bundle gate on every push\n    └── release.yml            ← GitHub release with .mcpb asset on version tags\n```\n\nThe shipped bundle contains just five files: `manifest.json`, `dist/server.js` (one dependency-free build), `assets/icon.png`, `LICENSE` and `README.md`.\n\n## Troubleshooting\n\n| Symptom | Likely cause & fix |\n|---|---|\n| 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**. |\n| Every Planhat tool appears twice | The bundle and an old manual config entry are both installed. Remove `mcpServers.planhat` from `claude_desktop_config.json`. |\n| 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. |\n| `HTTP 401 Unauthorized` in a tool result | The token is wrong, expired, or was rotated. Paste a fresh one. |\n| `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. |\n| `command not found: node` (manual install) | Install [Node.js](https://nodejs.org) 18 or newer, or point `command` at the full path to your `node` binary. |\n| Tool works but returns `[]` | Usually not an error: that Planhat resource is genuinely empty for your filters. |\n\n## For engineers\n\n```bash\nnpm install          # install dependencies\nnpm test             # offline test suite (never touches the live API)\nnpm run typecheck    # TypeScript type checking\nnpm run build        # produce dist/server.js\nnpm start            # run the built server over stdio\n```\n\nBuild the one-click bundle locally with `npm run build && npx -y @anthropic-ai/mcpb@2.1.2 pack . planhat.mcpb`.\n\nArchitecture notes, API quirks, and contribution rules live in [AGENTS.md](AGENTS.md) and [CONTRIBUTING.md](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).\n\n## License\n\n[MIT](LICENSE). Do what you like, no warranty.\n",
  "bytes": 9388,
  "sha": "f24b15a976f535ebbfa3ccdade0d4dcd9c2d3003893d44b074bcab30e0397b19",
  "repo_slug": "da-troll/planhat-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_da_troll_planhat_mcp_726c6179/readme"
}