@nooviai/noovichat-mcp

Model Context Protocol server for NooviChat — exposes Pipeline Pro, Follow-Ups, Atendimentos, Broadcasts, WhatsApp Templates, WAHA/UAZAPI integrations and other custom NooviChat features as tools that Claude Desktop, Claude Code, Cursor and VS Code can call.

What is this?

NooviChat-MCP is an MCP server that lets LLM-powered assistants (Claude, Cursor, etc.) interact with your NooviChat instance using natural language. Ask Claude to "move card #42 to the Negotiation stage" or "list all follow-ups scheduled for tomorrow" and the model uses these tools to get it done.

The server wraps the NooviChat REST API and exposes 270+ tools across 22 feature areas — every customization the NooviChat platform adds on top of Chatwoot, plus the most useful Chatwoot-native operations needed for them to work end-to-end.

Features exposed

| Area | Tools | Highlights | |---|---|---| | Pipeline Pro — core | 28 | Funnels, stages, cards CRUD, move/win/lost, bulk, GDPR restore | | Pipeline automations | 24 | CRUD, execute, dry-run, validate, audit logs, executions, templates | | Pipeline activities | 27 | Activities CRUD, sequences, templates, status transitions | | Pipeline sequences | 8 | Card-attached cadences, external trigger, analytics | | Pipeline webhooks | 9 | Managed CRUD + public token-only trigger endpoint | | Follow-Ups | 24 | Schedule, cancel, templates, items, variables, automations, reports | | Atendimentos | 29 | Appointments, services, professionals, partners, availability, Google Calendar sync | | Broadcasts | 14 | Mass-send WhatsApp campaigns, blacklist, pause/resume, duplicate | | WhatsApp Templates | 6 | Custom CRUD over Meta Cloud + sync from Meta | | WAHA | 14 | Self-hosted WhatsApp gateway: status, QR, pairing, sessions, settings, sync | | UAZAPI | 8 | Alternative WhatsApp gateway: status, settings, connect/disconnect, pairing | | Lead Scoring | 15 | Rules, logs, dashboard, distribution, trends, top leads, bulk recalc | | Internal Chat | 14 | Agent-to-agent DMs, groups, members, messages CRUD, mark read | | Companies | 6 | B2B grouping, search, CRUD | | Atendimento ext. | 12 | LGPD delete/export, bulk update, consent records, forwards, merge, history | | Google Calendar | 8 | Sync to/from, bulk sync, toggle, status, circuit breaker controls | | Captain AI hook | 7 | Preferences + 5 synchronous AI tasks (rewrite, summarize, reply, label, follow-up) | | Whitelabel (super_admin) | 16 | Branding, AI providers, scripts, audit logs, backups | | NooviLicense / NooviLabs / Audio | 0 (today) | No public API yet — JSDoc roadmaps included | | Total | 270 | Across 22 feature modules |

Install

The server is invoked by your MCP host (Claude Desktop, Cursor, etc.) as a subprocess via npx. You don't run it manually.

Claude Desktop / Claude Code

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) — or your Claude Code settings:

{
  "mcpServers": {
    "noovichat": {
      "command": "npx",
      "args": ["-y", "@nooviai/noovichat-mcp"],
      "env": {
        "NOOVICHAT_BASE_URL": "https://chat.example.com",
        "NOOVICHAT_API_TOKEN": "your-api-token-here",
        "NOOVICHAT_ACCOUNT_ID": "1"
      }
    }
  }
}

Restart the MCP host. The 138 tools become available to the model.

Cursor / VS Code (Continue)

Same pattern — point the MCP config at this package via npx. See your host's MCP documentation for the exact format.

Configuration

| Env var | Required | Purpose | |---|---|---| | NOOVICHAT_BASE_URL | yes | NooviChat instance URL (e.g., https://chat.example.com). No trailing slash. | | NOOVICHAT_API_TOKEN | yes | API access token from NooviChat → Profile → API Access. Belongs to a real agent — its permissions are the ceiling of what the MCP can do. | | NOOVICHAT_ACCOUNT_ID | optional | Default account ID. If set, you can omit account_id from individual tool calls. Required for single-tenant setups; multi-account operators may want to leave it unset and pass per-call. | | NOOVICHAT_TIMEOUT_MS | optional | HTTP request timeout in milliseconds (default 30000). |

Getting an API token

1. Log into your NooviChat instance as an admin or agent
2. Profile menu → API Access
3. Copy the token shown
4. Token inherits the agent's role and account membership — keep it scoped to what you need (don't use a super_admin token for routine LLM operations)

Usage examples

Ask Claude things like:

"List my open pipeline cards in the B2B Outbound funnel that are assigned to me and have lead_score above 60."

"Schedule a WhatsApp follow-up to contact #1234 saying 'Hi {{name}}, did you receive our proposal?' for 9am tomorrow."

"Move card #42 to the Won stage with value R$15,000 and note 'closed via discount + early payment'."

"Show me the conversion rate from Discovery to Demo stage in the last 30 days."

The model picks the right tools, fills the parameters, and calls them.

Available tools

A full inventory is generated from the source — see TOOLS.md (auto-generated, not committed yet).

To browse them grouped by feature area, look at src/tools/ — each file is one resource.

Development

# Install
pnpm install

# Type-check + lint + test
pnpm check

# Watch mode for local dev
pnpm dev

# Run the server pointing at a real NooviChat instance
NOOVICHAT_BASE_URL=https://chat.example.com \
NOOVICHAT_API_TOKEN=xxx \
NOOVICHAT_ACCOUNT_ID=1 \
pnpm start

Testing locally with Claude Desktop

In your Claude Desktop config, point at the local build:

{
  "mcpServers": {
    "noovichat-dev": {
      "command": "node",
      "args": ["/absolute/path/to/NooviChat-MCP/dist/index.js"],
      "env": { "NOOVICHAT_BASE_URL": "...", "NOOVICHAT_API_TOKEN": "..." }
    }
  }
}

Adding a new tool

1. Identify the resource (e.g., a new pipeline_widget route).
2. Create or edit the file in src/tools/<resource>.ts.
3. Follow the pattern in pipeline-cards.ts — server.registerTool(name, { title, description, inputSchema, annotations? }, handler).
4. Always wrap handlers in safeHandler(() => client.METHOD(...)) from _helpers.ts. Don't manually JSON-stringify.
5. If it's a new resource file, add the import + entry to src/tools/index.ts.
6. Add a test asserting registration.

Architecture

┌────────────────────────┐    stdio     ┌─────────────────────┐
│ Claude Desktop / Code  │ ◄──────────► │  noovichat-mcp      │
│ Cursor / VS Code (MCP) │              │  (this package)     │
└────────────────────────┘              └──────────┬──────────┘
                                                   │
                                              REST + api_access_token
                                                   │
                                                   ▼
                                        ┌─────────────────────┐
                                        │  NooviChat instance │
                                        │  (Rails 7.1 + Vue)  │
                                        └─────────────────────┘

• Transport: stdio (the standard MCP Desktop / Code / Cursor transport)
• Auth: api_access_token HTTP header (NooviChat / Chatwoot REST contract)
• Validation: Zod schemas inline per tool
• HTTP: native Node 20+ fetch with AbortController timeout
• SDK: @modelcontextprotocol/sdk

Releases

This package follows semver:

• Patch (0.1.x): bug fixes, doc updates, internal refactors
• Minor (0.x.0): new tools, new resources
• Major (x.0.0): breaking changes to existing tool signatures

Releases respect the NooviChat monorepo release-cadence rule: batched, never during business hours BR (Mon-Fri 08-19h BRT).

License

MIT — Copyright (c) 2026 Noovi.AI.

This project is forked from fazer-ai/mcp-chatwoot under MIT. The original copyright notice is preserved in LICENSE.

Related Noovi.AI projects

• @nooviai/n8n-nodes-noovichat — n8n community node (REST consumer, similar surface)
• NooviChat — the platform itself

Support

• Issues: https://github.com/Noovi-AI/noovichat-mcp/issues
• Docs: https://noovichat.com/docs
• Email: [email protected]