mcp-n8n-voice-orchestrator

README.md

[![npm version](https://img.shields.io/npm/v/mcp-n8n-voice-orchestrator.svg)](https://www.npmjs.com/package/mcp-n8n-voice-orchestrator)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

# mcp-n8n-voice-orchestrator

A lightweight, deterministic **Model Context Protocol (MCP)** bridge and reference architecture designed to connect **Claude (Sonnet/Haiku/Opus)** and **Claude Code** directly to self-hosted **n8n** instances, **Vapi.ai** voice pipelines, **Twilio**, and **WhatsApp Cloud API**.

## Why This Exists (The Ecosystem Gap)
While n8n provides general workflow nodes and Anthropic's MCP standardizes tool-calling, production voice and messaging pipelines suffer from three critical bottlenecks:
1. **Race Conditions & Webhook Concurrency:** Out-of-order webhook arrivals between Vapi end-of-call reports and WhatsApp follow-up triggers.
2. **Sub-Second Latency Requirements:** Voice agents require deterministic state lookup (<300ms) before triggering LLM tool calls.
3. **Lack of Standardized MCP Schemas for Self-Hosted Automation:** Developers repeatedly rebuild boilerplate JSON-RPC wrappers to expose n8n webhook endpoints as verified Claude MCP tools.

## Core Architecture
- `/mcp-server`: TypeScript MCP server exposing n8n webhook workflows as strict, Zod-validated tools for Claude Desktop and Claude API.
- `/workflows`: Production-grade n8n JSON blueprints for missed-call recovery, deterministic lead qualification, and multi-channel session handoff.
- `/state-machine`: Supabase / PostgreSQL idempotency tables and row-level locking schemas to prevent duplicate outbound dispatches.

## Quick Start
 
```bash
git clone [https://github.com/Code-With-Vishal/mcp-n8n-voice-orchestrator.git](https://github.com/Code-With-Vishal/mcp-n8n-voice-orchestrator.git)
cd mcp-n8n-voice-orchestrator
npm install
cp .env.example .env
npm run build

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3/5.0

Scored 2026-11-12 18:55 across 1 tool

Disambiguation5/5

With only a single tool, there is no possibility of confusing it with another; its purpose as a workflow dispatcher is unmistakable.

Naming Consistency4/5

The lone name follows a clear snake_case verb_noun pattern (dispatch_idempotent_n8n_workflow), though with one tool there is no pattern to actually be consistent across.

Tool Count2/5

A single tool is too thin for an orchestration server; dispatch is the only operation, leaving no room for status, verification, or management operations.

Completeness2/5

The surface offers fire-and-forget dispatch with no way to check workflow status, list available workflows, or handle failures, which are significant gaps for an orchestration role.

Maintenance

ActivityMaintained

ResponsivenessNo recent community issues

TDQS

Maintenance

Resources