Ploomes MCP Server

Unofficial Model Context Protocol server that connects AI agents to the Ploomes CRM REST API. Exposes 56 tools covering contacts, deals, tasks, pipelines, interactions, quotes, orders, products, fields, users, account management, and lookup/reference data.

Works with any MCP-compatible client: Claude Desktop, Claude Code, Cursor, VS Code (Copilot), and others.

---

Quick Start

One-command setup

npx ploomes-mcp-server init

The interactive wizard will:

1. Ask for your Ploomes User-Key
2. Ask where to install (Claude Desktop, Claude Code, Cursor, VS Code, or manual)
3. Ask if project-level or global
4. Write the config automatically

That's it. No cloning, no building, no manual config editing.

Non-interactive setup (scripts, CI, deploying to teammates)

Pass flags and the wizard skips every prompt:

# Configure every global client (Claude Desktop + Claude Code + Cursor) in one shot
npx ploomes-mcp-server init --key YOUR_USER_KEY --target all --yes

# Single target
npx ploomes-mcp-server init --key YOUR_USER_KEY --target claude-desktop --yes

# Read the key from the environment instead of the command line
export PLOOMES_USER_KEY=YOUR_USER_KEY
npx ploomes-mcp-server init --target all --yes

Flags:

Flag	Value	Description
--key, -k	<user-key>	Ploomes User-Key. Falls back to PLOOMES_USER_KEY env var if omitted.
--target, -t	see below	Which client to configure. Required for non-interactive mode.
--yes, -y	(flag)	Overwrite existing ploomes entries without asking.

--target values: claude-desktop, claude-code-project, claude-code-global, cursor, vscode, all (every global client), manual (print JSON only).

Security: putting the key directly in the command line leaves it in your shell history. Prefer export PLOOMES_USER_KEY=… first, then call init --target all --yes.

Prerequisites

• Node.js 20+ (uses native fetch)
• A Ploomes User-Key (get it from Ploomes > Settings > Integration > API Key)

---

Manual Setup

If you prefer to configure manually, add this to your MCP client config:

Claude Desktop

Config file location:

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

macOS / Linux:

{
  "mcpServers": {
    "ploomes": {
      "command": "npx",
      "args": ["-y", "ploomes-mcp-server"],
      "env": {
        "PLOOMES_USER_KEY": "your-key-here"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "ploomes": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "ploomes-mcp-server"],
      "env": {
        "PLOOMES_USER_KEY": "your-key-here"
      }
    }
  }
}

Important: On Windows you must wrap the command with cmd /c. MCP clients (Claude Desktop, Claude Code, Cursor) spawn commands without a shell, and Node's spawn() on Windows cannot resolve .cmd/.bat files directly. Using "command": "npx" or "command": "npx.cmd" alone results in the server failing to start silently — the config is saved, but no tools appear in the chat. cmd /c npx delegates to a real shell that handles PATH and extension resolution.

If you already tried init on an older version and the tools aren't showing up, re-run:

npx ploomes-mcp-server@latest init
npx ploomes-mcp-server@latest doctor

Claude Code

Project-level .mcp.json:

{
  "mcpServers": {
    "ploomes": {
      "command": "npx",
      "args": ["-y", "ploomes-mcp-server"],
      "env": {
        "PLOOMES_USER_KEY": "your-key-here"
      }
    }
  }
}

Or via CLI:

claude mcp add ploomes -- npx -y ploomes-mcp-server -e PLOOMES_USER_KEY=your-key-here

Cursor

File: ~/.cursor/mcp.json

{
  "mcpServers": {
    "ploomes": {
      "command": "npx",
      "args": ["-y", "ploomes-mcp-server"],
      "env": {
        "PLOOMES_USER_KEY": "your-key-here"
      }
    }
  }
}

Remote (HTTP Transport)

MCP_TRANSPORT=http MCP_HTTP_PORT=3000 PLOOMES_USER_KEY=your-key npx ploomes-mcp-server

Then point your MCP client to https://your-server.com/mcp (use a reverse proxy for HTTPS).

Windows users: In all JSON examples above, replace the command / args with the cmd /c npx -y ploomes-mcp-server pattern shown in the Claude Desktop Windows example. MCP clients on Windows cannot spawn .cmd files directly — you must delegate through cmd. The npx ploomes-mcp-server init wizard does this automatically.

---

CLI

npx ploomes-mcp-server                                           # Start the MCP server (stdio)
npx ploomes-mcp-server init                                      # Interactive setup wizard
npx ploomes-mcp-server init --key KEY --target all --yes         # Non-interactive
npx ploomes-mcp-server init --target claude-desktop --yes        # Uses PLOOMES_USER_KEY env
npx ploomes-mcp-server doctor                                    # Diagnose configs and spawn behavior
npx ploomes-mcp-server --help                                    # Show usage
npx ploomes-mcp-server --version                                 # Show version

Environment Variables

Variable	Required	Default	Description
PLOOMES_USER_KEY	Yes	—	Your Ploomes API key
MCP_TRANSPORT	No	stdio	stdio or http
MCP_HTTP_PORT	No	3000	HTTP port (when using http transport)
PLOOMES_BASE_URL	No	https://api2.ploomes.com	Ploomes API base URL
PLOOMES_RATE_LIMIT	No	120	Max requests per minute

---

Tools Overview

CRUD Tools (44)

Category	Tools	Operations
Contacts	5	list, get, create, update, delete
Deals	8	list, get, create, update, delete, win, lose, reopen
Tasks	6	list, get, create, update, delete, finish
Interactions	5	list, get, create, update, delete
Quotes	5	list, get, create, update, delete
Orders	5	list, get, create, update, delete
Products	5	list, get, create, update, delete
Pipelines	2	list pipelines, list stages
Fields	1	list custom fields
Users	1	list users
Account	1	get account info

Lookup Tools (12)

Reference tools for discovering valid IDs, enum values, and dropdown options used by the CRUD tools above.

Tool	Description
ploomes_contacts_types_list	Contact types (Person, Company, etc.)
ploomes_contacts_status_list	Contact statuses (Active, Inactive, etc.)
ploomes_contacts_origins_list	Contact origins (Website, Referral, etc.)
ploomes_deals_status_list	Deal statuses (Open, Won, Lost)
ploomes_deals_loss_reasons_list	Loss reasons for marking deals as lost
ploomes_tasks_types_list	Task types (Call, Meeting, Email, etc.)
ploomes_currencies_list	Available currencies
ploomes_fields_entities_list	Entities that support custom fields
ploomes_fields_types_list	Custom field data types
ploomes_fields_options_tables_list	Dropdown option tables
ploomes_fields_options_list	Options within a dropdown table
ploomes_orders_stages_list	Order workflow stages

Total: 56 tools

See Tools Reference for complete documentation of every tool.

---

Documentation

Document	Description
Architecture	System design, data flow, component breakdown
Configuration	Environment variables, transport options, deployment
Tools Reference	All 56 tools with parameters, examples, and annotations
Testing & Debugging	MCP Inspector, Claude Desktop, Claude Code setup
Examples & Recipes	Real-world CRM workflows with step-by-step tool calls

---

Project Structure

ploomes-mcp-server/
├── src/
│   ├── index.ts              # Entry point — CLI routing + transport detection
│   ├── server.ts             # Creates McpServer, registers all tools
│   ├── cli/
│   │   └── setup.ts          # Interactive setup wizard (npx init)
│   ├── client/
│   │   ├── rate-limiter.ts   # Sliding window rate limiter (120 req/min)
│   │   ├── odata-builder.ts  # OData v4 query parameter builder
│   │   └── ploomes-client.ts # HTTP client with retry & error handling
│   ├── tools/
│   │   ├── contacts.ts       # 5 tools — CRUD
│   │   ├── deals.ts          # 8 tools — CRUD + Win/Lose/Reopen
│   │   ├── tasks.ts          # 6 tools — CRUD + Finish
│   │   ├── pipelines.ts      # 2 tools — List pipelines & stages
│   │   ├── interactions.ts   # 5 tools — CRUD
│   │   ├── quotes.ts         # 5 tools — CRUD
│   │   ├── orders.ts         # 5 tools — CRUD
│   │   ├── products.ts       # 5 tools — CRUD
│   │   ├── lookups.ts        # 12 tools — Reference/lookup data
│   │   ├── fields.ts         # 1 tool  — List fields
│   │   ├── users.ts          # 1 tool  — List users
│   │   └── account.ts        # 1 tool  — Account info
│   ├── types/
│   │   ├── ploomes.ts        # TypeScript interfaces for all entities
│   │   └── schemas.ts        # Shared Zod schemas (OtherProperties, etc.)
│   └── utils/
│       ├── formatter.ts      # Standardized MCP response builders
│       └── logger.ts         # stderr logger (debug/info/warn/error)
├── dist/                     # Compiled JavaScript (npm run build)
├── docs/                     # Extended documentation
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

---

Key Design Decisions

• Zero unnecessary dependencies — only @modelcontextprotocol/sdk, zod, and dotenv. Uses Node 20's native fetch.
• TypeScript strict mode — full type safety, no any.
• Every request rate-limited — sliding window prevents hitting Ploomes' 120 req/min limit.
• Automatic retries — exponential backoff on HTTP 429 (rate limit) and 5xx (server errors), up to 3 retries.
• Descriptive errors — "Resource not found: /Contacts(999)" instead of "Error".
• Tool descriptions in English — optimized for LLM understanding. Data from Ploomes may be in pt-BR.
• Lookup tools — dedicated tools for discovering valid IDs (types, statuses, origins, currencies, etc.) so the AI agent can self-serve without guessing.
• Shared Zod schemas — OtherProperties schema reused across all tools that support custom fields.
• One-command setup — npx ploomes-mcp-server init configures any supported MCP client.
• No bundler — plain tsc compilation to dist/.

---

Tech Stack

Component	Technology
Runtime	Node.js 20+
Language	TypeScript 5.x (strict mode)
MCP SDK	@modelcontextprotocol/sdk
Validation	zod
HTTP client	Native fetch
Build	tsc (no bundler)
Transport	stdio (local) / Streamable HTTP (remote)
Distribution	npm (npx ploomes-mcp-server)

---

Troubleshooting (Windows)

Symptom: npx ploomes-mcp-server init succeeds, writes the config, but the tools never appear in Claude Desktop / Claude Code / Cursor.

Cause: Older versions generated "command": "npx.cmd". MCP clients on Windows spawn commands without a shell, so Node's spawn() cannot resolve .cmd extensions directly. The server fails to start and the client shows no error in the UI.

Fix:

npx ploomes-mcp-server@latest init
npx ploomes-mcp-server@latest doctor

The updated wizard generates "command": "cmd" with "args": ["/c", "npx", "-y", "ploomes-mcp-server"], which works across Claude Desktop, Claude Code, Cursor, and VS Code on Windows.

Still stuck?

1. Fully quit Claude Desktop (right-click system tray icon → Quit — closing the window is not enough).
2. Inspect logs at %APPDATA%\Claude\logs\mcp-server-ploomes.log.
3. Run npx ploomes-mcp-server doctor — it validates your config and tests that cmd /c npx actually spawns.
4. If you edited the config manually, ensure the JSON is valid (commas, braces) and the "ploomes" entry sits inside "mcpServers".

---

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes
4. Build and test (npm run build)
5. Test with MCP Inspector (see Testing)
6. Submit a pull request

---

License

MIT