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.

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

File: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

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

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).

CLI

npx ploomes-mcp-server              # Start the MCP server (stdio)
npx ploomes-mcp-server init         # Interactive setup wizard
npx ploomes-mcp-server --help       # Show usage
npx ploomes-mcp-server --version    # Show version

Environment Variables

Tools Overview

CRUD Tools (44)

Lookup Tools (12)

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

Total: 56 tools

See Tools Reference for complete documentation of every tool.

Documentation

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

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