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