NinjaPipe MCP Server

MCP server that exposes read-only NinjaPipe contacts to AI assistants (Cursor, Claude Desktop, etc.). Access is strictly limited to the workspace tied to your API key; no workspace ID is ever accepted from the client.

Tools

• list_contacts – List contacts (optional: search, limit, page).
• get_contact – Get one contact by ID (required: id UUID).
• create_contact – Create a contact in the workspace (at least first_name or last_name; optional: email, phone, status, owner_id, company_id, fields). Requires API key with write permission.
• update_contact – Update a contact by ID (required: id; optional: first_name, last_name, email, phone, status, owner_id, company_id, fields). Only provided fields are updated. Requires API key with write permission.
• list_companies – List companies (optional: page, limit, search, status, owner_id). 1:1 with Companies.js.
• get_company – Get one company by ID (required: id). 1:1 with CompanyDetailsPage.
• create_company – Create a company (required: name; optional: industry, website, phone, email, status, owner_id, fields). 1:1 with Companies / CompanyDetailsPage. Requires write permission.
• update_company – Update a company by ID (required: id; optional: name, industry, website, phone, email, status, owner_id, fields). 1:1 with CompanyDetailsPage. Requires write permission.
• list_deals – List deals (optional: page, limit, search, status, owner_id, sort_by, sort_order). 1:1 with Deals.js.
• get_deal – Get one deal by ID (required: id). 1:1 with Deals.js.
• create_deal – Create a deal (required: name; optional: value, status, owner_id, contact_id, company_id, fields). 1:1 with Deals.js. Requires write permission.
• update_deal – Update a deal by ID (required: id; optional: name, value, status, owner_id, contact_id, company_id, fields). 1:1 with Deals.js. Requires write permission.
• list_projects – List task projects (optional: page, limit, search, status, priority, sort_by, sort_order). 1:1 with Tasks.js.
• get_project – Get one task project by ID (required: id). 1:1 with Tasks.js / ProjectTasks.js.
• create_project – Create a task project (required: name; optional: description, status, priority, due_date, team, tags). 1:1 with Tasks.js. Requires write permission.
• update_project – Update a task project (required: id; optional: name, description, status, priority, due_date, team, tags). 1:1 with Tasks.js / ProjectTasks.js. Requires write permission.
• list_tasks – List tasks in a project (required: project_id; optional: status, priority, parent_id, sort_by, sort_order). 1:1 with ProjectTasks.js.
• get_task – Get one task by project_id and task_id (required: project_id, task_id). 1:1 with ProjectTasks.js.
• create_task – Create a task in a project (required: project_id, title; optional: description, status, priority, due_date, estimated_hours, actual_hours, tags, parent_id, order_index, settings_json). 1:1 with ProjectTasks.js / CreateTaskModal. Requires write permission.
• update_task – Update a task (required: project_id, task_id; optional: title, description, status, priority, due_date, estimated_hours, actual_hours, tags, parent_id, order_index, settings_json). 1:1 with ProjectTasks.js. Requires write permission.
• list_forms – List forms (optional: page, limit, search, status, sort_by, sort_order). 1:1 with Forms.js.
• get_form – Get one form by ID (required: id). 1:1 with Forms.js / FormDesigner.js.
• create_form – Create a form (required: name; optional: description, slug, status, fields_json, settings_json). Slug auto-generated from name if omitted. 1:1 with Forms.js / CreateFormModal. Requires write permission.
• update_form – Update a form (required: id; optional: name, description, slug, status, fields_json, settings_json). 1:1 with Forms.js / FormDesigner.js. Requires write permission.
• list_pipelines – List pipelines (optional: page, limit, type [contacts|deals|general], archived).
• get_pipeline – Get one pipeline by ID (required: id).
• create_pipeline – Create a pipeline (required: name, pipeline_type [contacts|deals|general], stages array of { id, name, color }; optional: description). Requires API key with write permission.
• update_pipeline – Update a pipeline by ID (required: id; optional: name, description, stages, settings_json). Requires API key with write permission.
• list_pipeline_items – List pipeline items (cards) in a pipeline (required: pipeline_id; optional: stage_id). 1:1 with ViewPipeline.
• get_pipeline_item – Get one pipeline item by pipeline ID and item ID (required: pipeline_id, item_id). 1:1 with ViewPipeline.
• create_pipeline_item – Add a pipeline item (card) to a pipeline (required: pipeline_id, title, stage_id; optional: subtitle, description, item_type, reference_id, priority, value, assigned_to, due_date, tags, avatar, company, phone, email, order_index, checklist, custom_fields, comments, attachments, metadata). 1:1 with AddPipelineItemModal / ViewPipeline. Requires write permission.
• update_pipeline_item – Update a pipeline item (required: pipeline_id, item_id; optional: title, subtitle, description, stage_id, item_type, reference_id, priority, value, assigned_to, due_date, tags, avatar, company, phone, email, order_index, last_activity, metadata, checklist, custom_fields, comments, attachments). 1:1 with ViewPipeline card save. Requires write permission.

Prerequisites

• Node.js 18+
• A NinjaPipe API key (create one in your NinjaPipe workspace: Settings → API keys). The key is bound to a single workspace. Use read for list/get only; use write to also create contacts.

Environment

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | NINJAPIPE_API_KEY | Yes | — | Your NinjaPipe API key (e.g. np_...). | | NINJAPIPE_API_URL | No | https://ninjapipe.app | NinjaPipe API base URL (no trailing slash). Use http://localhost:3001 only for local development. |

Use in Cursor

1. Get your NinjaPipe API key
   In NinjaPipe: open your workspace → Settings (or Account) → API keys → create a key (read and/or write). Copy the key (starts with np_).

2. Add the MCP server in Cursor

   • Open Cursor Settings → MCP (or Features → MCP).
   • Add a new MCP server.
   • Using the npm package (recommended):

   {
     "mcpServers": {
       "ninjapipe": {
         "command": "npx",
         "args": ["-y", "ninjapipe-mcp"],
         "env": {
           "NINJAPIPE_API_KEY": "np_YOUR_KEY_HERE",
           "NINJAPIPE_API_URL": "https://ninjapipe.app"
         }
       }
     }
   }

   Replace np_YOUR_KEY_HERE with your real key. You can omit NINJAPIPE_API_URL to use the default production API (https://ninjapipe.app).

   Local development: To point at your own API (e.g. http://localhost:3001), set NINJAPIPE_API_URL to that base URL.

3. Restart Cursor (or reload the window) so it picks up the new MCP server.

4. Use it in chat
   In a Cursor chat, ask e.g.: “List my NinjaPipe contacts” or “Get NinjaPipe contact with id …”. The model will call list_contacts or get_contact; the server will call the NinjaPipe API with your key and return only that workspace’s data.

Security

• Access is limited to the workspace tied to your API key. The server never sends or accepts a workspace ID; the key alone determines the workspace.
• Do not share your API key. Store it only in your local MCP config (env) and never commit it.

No dependencies

This server uses only Node.js built-ins (readline, fetch). No npm install is required to run it.

Troubleshooting

• "No server info found" / "Server not yet created"
  Cursor may use Content-Length (LSP-style) framing; the server now auto-detects it and responds in the same format. Ensure:

  1. Path is absolute in your MCP config (e.g. /Users/you/.../scripts/ninjapipe-mcp/index.js).
  2. Env is set in the MCP config: NINJAPIPE_API_KEY and optionally NINJAPIPE_API_URL.
  3. Node 18+ is on your PATH when Cursor runs (needed for fetch).

  To debug, set NINJAPIPE_MCP_DEBUG=1 in the server env and check Cursor’s MCP log (or run the server manually and pipe a message to see stderr).

• Manual test
  From a terminal (defaults to production API; set NINJAPIPE_API_URL to http://localhost:3001 for local dev):

  npx -y ninjapipe-mcp
  # or with env:
  export NINJAPIPE_API_KEY=np_your_key
  export NINJAPIPE_API_URL=https://ninjapipe.app
  export NINJAPIPE_MCP_DEBUG=1
  echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | npx -y ninjapipe-mcp

  You should see a JSON-RPC response with serverInfo and capabilities on stdout.