plutio-mcp

A Model Context Protocol (MCP) server for Plutio — the all-in-one business platform for CRM, projects, invoicing, proposals, contracts, forms, time tracking, and scheduling.

Gives Claude (and any other MCP client) structured, safe access to every major resource in your Plutio workspace via one concise tool per resource.

What you get

• 31 resource-group tools covering CRM, project management, time tracking, financial, documents, forms, communication, scheduling, knowledge, files, automations, and admin.

• 4 escape-hatch tools (plutio_api_reference, plutio_workspace_schema, plutio_rate_limit_status, plutio_request) for edge cases, workspace introspection, and agent self-orientation.

• 4 analytics tools (plutio_mrr_snapshot, plutio_upcoming_renewals, plutio_invoice_aging, plutio_cashflow_forecast) — single-call reports that replace multi-step manual aggregations.

• 1 compound lookup tool (plutio_client_360) — fetches a person + their company + projects + invoices + subscriptions in one call.

• 5 MCP resources (plutio://people/{id}, plutio://companies/{id}, plutio://projects/{id}, plutio://invoices/{id}, plutio://tasks/{id}) for clients that support resource browsing.

• Read-only by default — no accidental destructive writes until you explicitly enable them.

• OAuth2 with auto-refresh — client-credentials grant; tokens refresh ~1 minute before expiry.

• Built-in rate limiting — a token bucket capped at Plutio's 1000 req/hr default; requests queue transparently.

• MongoDB-style filtering — pass rich query objects directly ($or, $regex, $gte, etc.).

• Bulk operations for resources that support them.

• Typed end-to-end with Zod → JSON Schema on the wire.

Quick start

1. Install

npm install -g @thecreativelabs/plutio-mcp
# or run without installing:
npx @thecreativelabs/plutio-mcp

2. Get Plutio API credentials

In your Plutio workspace go to Settings → API Manager → Create Connection. You'll get a Client ID and Client Secret. Copy them — you won't see the secret again.

3. Configure Claude Desktop / Claude Code

Add to your MCP config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or .mcp.json / .claude/settings.json for Claude Code):

{
  "mcpServers": {
    "plutio": {
      "command": "npx",
      "args": ["-y", "@thecreativelabs/plutio-mcp"],
      "env": {
        "PLUTIO_CLIENT_ID": "your_client_id",
        "PLUTIO_CLIENT_SECRET": "your_client_secret",
        "PLUTIO_BUSINESS": "your_workspace_slug",
        "PLUTIO_READ_ONLY": "true"
      }
    }
  }
}

PLUTIO_BUSINESS is your workspace slug — the subdomain part of <slug>.plutio.com. If your OAuth client is tied to exactly one business, you can omit it and the server will auto-detect from the token response. When the client has access to multiple businesses, you must set it explicitly.

Restart Claude. You should now see plutio_* tools available.

4. Using ChatGPT?

plutio-mcp speaks HTTP natively since v0.7.0. Set PLUTIO_MCP_HTTP=true and the server listens on http://<host>:<port>/mcp instead of stdio. See examples/10-chatgpt-setup.md for the full walkthrough (local + ngrok, or hosted on Fly.io).

5. Enable writes (when you trust it)

Set PLUTIO_READ_ONLY=false to unlock create, update, delete, archive, unarchive, and bulk operations.

How writes actually work inside Plutio's API. Plutio's public API only supports mutations via bulk endpoints — PUT /{resource}/{id} returns 403 everywhere. The MCP server handles this transparently: single-record update/delete/archive/unarchive actions route through /bulk internally, so from your perspective the tool interface is the usual single-record CRUD. You don't need to think about it — but it explains the version bump to 0.3.0.

Environment variables

See .env.example.

Tool catalog

Every resource tool uses the same shape:

plutio_<resource>({ action: "list"|"get"|"create"|"update"|"delete"|"archive"|"bulk_*", ...args })

CRM

• plutio_people — contacts, clients, leads, team members

• plutio_companies — organizations/accounts

• plutio_notes — free-form notes on any record

Project management

• plutio_projects

• plutio_tasks

• plutio_task_boards · plutio_task_groups · plutio_statuses

Time tracking

• plutio_time_entries — billable/non-billable logs (API path: /time-tracks)

• plutio_time_categories

Financial

• plutio_invoices

• plutio_invoice_subscriptions — recurring invoices

• plutio_transactions — payments

Documents

• plutio_proposals

• plutio_contracts

Forms / leads / marketing

• plutio_forms

• plutio_form_responses — raw submissions before qualification

Communication

• plutio_conversations · plutio_comments (comments requires entityType + entityId in the query)

Scheduling

• plutio_schedules — availability windows

• plutio_events — calendar entries

Knowledge

• plutio_templates · plutio_canned_responses · plutio_wiki_pages · plutio_items

Files

• plutio_file_folders · plutio_files

Analytics / admin

• plutio_dashboards

• plutio_custom_fields

• plutio_automations — Plutio's native node-based automation workflows (list + create only; delete and single-GET are blocked by the REST API)

• plutio_businesses (workspace settings — read-only)

Analytics (v0.6.0)

• plutio_mrr_snapshot — active subscriptions aggregated into MRR, ARR, by frequency, top clients.

• plutio_upcoming_renewals — subs billing within the next N days (default 30), sorted by date.

• plutio_invoice_aging — unpaid invoices bucketed by days overdue (current / 30–60 / 60–90 / 90+).

• plutio_cashflow_forecast — projects expected income over N days by expanding each sub's recurrence.

Compound (v0.6.0)

• plutio_client_360 — one call, everything about a client: person + company + projects + invoices + subs.

Proposal builder (v0.8.0)

• plutio_list_proposal_presets — see shipped presets (web-design, seo-services, consulting, creative-services, coaching).

• plutio_proposal_from_preset — create a fully-populated proposal (blocks + items + client link) in one call.

• plutio_analyze_proposal — inspect a past proposal's structure to mirror it for a new client.

Contract builder (v0.9.0)

• plutio_list_contract_presets — shipped presets (service-agreement, nda).

• plutio_contract_from_preset — create a contract end-to-end with {{ variable }} substitution. Note: shipped presets contain TODO placeholders for legal clauses — replace before sending for signature.

Template extractor (v0.10.0)

• plutio_template_to_preset — read any of your existing Plutio contract/proposal templates and emit a preset JSON ready for the builders. Run once per template, save to disk, your real prose becomes available to AI generation forever. See examples/13.

Custom Pages + Custom Fields config (v0.10.2)

• plutio_dashboard_pages — list/get/create new pages on any of Plutio's role dashboards (Settings → Custom Pages). Update + delete blocked by REST (use UI).

• plutio_create_dashboard_page_from_preset — instantiate a page from a starter scaffold (client-welcome, project-status) with content blocks pre-populated. Plutio's native {{ client.name }} / {{ business.name }} tokens render at view time.

• plutio_apply_custom_fields_bundle — create a curated set of custom fields in one call. Shipped bundles: lead-intake, client-onboarding. Skips fields whose (entityType, title) already exists. See examples/14.

Escape hatches

• plutio_api_reference — compact map of every tool + API path. Call first when unsure.

• plutio_workspace_schema — introspects custom fields. Returns {entityType: {fieldTitle: {_id, inputType, options: {optionLabel: optionId}}}}. Cached 5 min.

• plutio_request — raw API passthrough: { method, path, query?, body? }.

• plutio_rate_limit_status — remaining requests in the current hour.

MCP resources (v0.6.0)

Some MCP clients let you browse typed resources. The server advertises these URI templates:

• plutio://people/{id} · plutio://companies/{id} · plutio://projects/{id} · plutio://invoices/{id} · plutio://tasks/{id}

Example prompts

Once configured, try these in Claude:

• "Use Plutio to list my 10 most recent invoices by due date."

• "Find all active projects where the client is 'Acme Corp'."

• "Show me form responses from the last 7 days that haven't been converted to people yet."

• "How much billable time did I log against project ABC in March?"

• (with writes enabled) "Create a follow-up task on project ABC due next Monday."

📖 See examples/ for 6 fully worked end-to-end workflows

Each example shows the user prompt, the exact tool calls Claude will make, and a realistic answer. All verified against a live workspace.

Filtering syntax

List actions accept a query object that supports Plutio's MongoDB-style operators:

{
  "action": "list",
  "query": {
    "status": "incomplete",
    "createdAt": { "$gte": "2026-01-01" },
    "$or": [
      { "tags": { "$in": ["lead", "hot"] } },
      { "companyId": "5f4..." }
    ]
  },
  "limit": 50,
  "sort": "-createdAt"
}

Custom fields

Plutio lets you define custom fields on any resource. To set them on create/update:

{
  "action": "update",
  "id": "5f4...",
  "data": {
    "customFields": [
      { "_id": "<custom_field_id>", "value": "Enterprise" }
    ]
  }
}

Fetch the custom-field definitions with plutio_custom_fields to see IDs and types.

Development

# clone + install
git clone https://github.com/thecreativelabs/plutio-mcp.git
cd plutio-mcp
npm install

# dev mode (watch + reload)
npm run dev

# typecheck / build
npm run typecheck
npm run build

# run against your env
PLUTIO_CLIENT_ID=... PLUTIO_CLIENT_SECRET=... node dist/index.js

Adding a new resource

All resources live in src/tools/registry.ts. Add a new entry and it's automatically exposed as a tool:

{
  name: "my_resource",
  path: "my-resource",
  category: "crm",
  description: "...",
  archive: true,
  bulk: true,
}

Adding a specialized action

For endpoints that don't fit the CRUD pattern (e.g. sending an invoice, publishing a proposal, starting a timer), add a standalone tool file under src/tools/ and register it in src/tools/index.ts. See escape-hatch.ts for the pattern.

Design choices

Known limitations

Lifecycle actions (Send Invoice, Publish Proposal, Sign Contract, Start/Stop Timer) are not supported by Plutio's public REST API. Live probing confirmed:

• PUT /invoices/bulk { status: "sent" } returns HTTP 200 but silently drops the status field.

• POST /invoices/{id}/send and every variant returns 403.

• The Plutio web app handles these via Meteor methods over WebSocket/DDP, which is not part of the public API surface.

Practical workarounds:

1. Trigger lifecycle actions in the Plutio web UI, then use this server to read the resulting state.

2. If you've reverse-engineered a specialized endpoint yourself, invoke it via plutio_request.

3. For status-aware logic (e.g., "find all overdue invoices"), read the status and time fields — they're populated server-side once the Plutio app performs the transition.

If Plutio ever exposes these actions publicly, plutio_request will work without any server update.

Roadmap

• Workspace introspection — plutio_workspace_schema (v0.4.0)

• Transparent bulk routing — single-record writes use /bulk internally (v0.3.0)

• Webhook support (once Plutio documents webhook endpoints)

• MCP resources (alongside tools) for read-heavy flows — expose plutio://people/{id} URIs

• Optional OpenAPI export of the generated schema

• SSE / streaming transport for hosted deployments

• Mocked-API integration test suite

Contributions welcome — see Contributing.

Contributing

1. Fork the repo and create a feature branch.

2. npm install && npm run typecheck before you push.

3. Open a PR describing the problem you're solving and any API references.

Design principle: don't grow the tool count blindly. Before adding a tool, ask whether it can fit the existing resource-grouped pattern or belongs in plutio_request. The fewer tools, the better agents perform.

License

MIT © TheCreativeLabs

Disclaimer

This is an unofficial, community-maintained integration. Not affiliated with or endorsed by Plutio.