CareFlow MCP 🏥

Production-ready healthcare workflow automation powered by n8n and the Model Context Protocol. Enables Claude and other AI assistants to trigger HIPAA-compliant patient task management workflows through natural language.

![NPM Version](https://www.npmjs.com/package/careflow-mcp) ![TypeScript](https://www.typescriptlang.org/) ![MCP SDK](https://github.com/modelcontextprotocol/sdk) ![License: MIT](https://opensource.org/licenses/MIT) ![mcp.so](https://mcp.so)

🏥 Healthcare-Ready: Includes comprehensive HIPAA compliance documentation and patient task management workflows.

Features

🚀 Trigger Workflows - Execute n8n workflows via webhook with custom payloads
📋 List Workflows - Query all active workflows from your n8n instance
📊 Check Status - Monitor workflow execution status in real-time
🏥 Healthcare-Ready - Built-in support for patient task workflows
🔒 Type-Safe - Full TypeScript support with Zod validation
⚡ Production-Ready - Comprehensive error handling and logging
🛠️ MCP Standard - Compatible with Claude Desktop and other MCP clients

📚 Documentation & Examples

[Case Studies](.[/case-studies/README.md)] - 5 real-world implementation examples with ROI metrics
HEALTHCARE.md - Comprehensive HIPAA compliance guide (our differentiator!)
Example Workflows - Importable n8n workflow JSON files

Quick Start with Examples

# 1. Import workflow to n8n
examples/healthcare-patient-task-workflow.json

# 2. Configure credentials in n8n

# 3. Ask Claude:
"Create a patient task for ID P12345 in the Patient Care workflow"

Tools Exposed

| Tool | Description | Required Params | |------|-------------|----------------| | trigger_workflow | Triggers an n8n workflow by name with JSON payload | workflowName, payload | | list_workflows | Lists all active workflows from n8n | None | | get_workflow_status | Checks execution status by ID | executionId | | create_patient_task | Sends structured patient task to workflow | workflowName, patientId, taskType |

Prerequisites

Node.js >= 18.0.0
n8n instance (cloud or self-hosted) with API access
n8n API Key (generate in n8n Settings > API)

Installation

Option 1: Via Smithery (Easiest)

Install directly from mcp.so using Smithery:

npx @smithery/cli install careflow-mcp

This will automatically:

Install the package
Add to your Claude Desktop config
Prompt for required environment variables

Option 2: NPM Installation

npm install -g careflow-mcp

Option 3: From Source

# Clone the repository
git clone https://github.com/pratapsfdc22-dev/careflow-mcp.git
cd careflow-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Link globally (optional)
npm link

Configuration

1. Create Environment File

cp .env.example .env

2. Configure Environment Variables

Edit .env with your n8n credentials:

# Base URL of your n8n instance
N8N_BASE_URL=https://your-n8n-instance.com

# n8n API Key (Settings > API > Create API Key)
N8N_API_KEY=n8n_api_xxxxxxxxxxxxxxxxxxxxxxxx

# Optional: Webhook Secret
N8N_WEBHOOK_SECRET=your_webhook_secret

3. Configure Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "n8n-workflow": {
      "command": "node",
      "args": [
        "/path/to/careflow-mcp/dist/index.js"
      ],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your_api_key_here",
        "N8N_WEBHOOK_SECRET": "your_webhook_secret"
      }
    }
  }
}

Using npm global install:

{
  "mcpServers": {
    "n8n-workflow": {
      "command": "careflow-mcp",
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your_api_key_here"
      }
    }
  }
}

Usage Examples

1. Trigger a Workflow

// Ask Claude:
"Trigger the 'Customer Onboarding' workflow with this data:
{ email: 'user@example.com', name: 'John Doe' }"

2. List All Active Workflows

// Ask Claude:
"Show me all active n8n workflows"

3. Check Workflow Execution Status

// Ask Claude:
"Check the status of execution ID: abc123"

4. Create a Patient Task

// Ask Claude:
"Create a high-priority follow-up task for patient ID P12345
in the 'Patient Care' workflow, due tomorrow"

Development

Build

npm run build

Watch Mode

npm run watch

Run Locally

npm run dev

Clean Build Artifacts

npm run clean

Project Structure

careflow-mcp/
├── src/
│   ├── index.ts        # Main MCP server implementation
│   └── types.ts        # TypeScript types and Zod schemas
├── dist/               # Compiled JavaScript (generated)
├── .env.example        # Environment variable template
├── .gitignore          # Git ignore rules
├── package.json        # NPM package configuration
├── tsconfig.json       # TypeScript configuration
└── README.md           # This file

API Reference

trigger_workflow

Triggers an n8n workflow by name with optional JSON payload.

Input: ``typescript { workflowName: string; // Name of the workflow payload?: object; // Optional JSON data } ``

Output: ``json { "success": true, "workflowId": "abc123", "workflowName": "Customer Onboarding", "response": { ... } } ``

list_workflows

Lists all active workflows from n8n instance.

Input: None

Output: ``json { "success": true, "count": 5, "workflows": [ { "id": "abc123", "name": "Customer Onboarding", "active": true, "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2024-01-15T12:00:00.000Z" } ] } ``

get_workflow_status

Checks the execution status of a workflow run.

Input: ``typescript { executionId: string; // Execution ID from trigger response } ``

Output: ``json { "success": true, "execution": { "id": "exec123", "workflowId": "abc123", "finished": true, "status": "success", "startedAt": "2024-01-15T12:00:00.000Z", "stoppedAt": "2024-01-15T12:00:05.000Z" } } ``

create_patient_task

Sends a structured patient task to an n8n workflow.

Input: ``typescript { workflowName: string; // Target workflow patientId: string; // Patient identifier taskType: string; // Task type priority?: "low" | "medium" | "high" | "urgent"; description?: string; dueDate?: string; // ISO 8601 format assignedTo?: string; metadata?: object; } ``

Output: ``json { "success": true, "workflowId": "abc123", "workflowName": "Patient Care", "task": { ... }, "response": { ... } } ``

Error Handling

The server implements comprehensive error handling with proper MCP error codes:

Invalid Parameters - ErrorCode.InvalidParams
Method Not Found - ErrorCode.MethodNotFound
Internal Error - ErrorCode.InternalError

All errors include descriptive messages for debugging.

Security Best Practices

Never commit .env - Always use .env.example for templates
Rotate API keys - Regularly update your n8n API keys
Use webhook secrets - Add authentication to webhook triggers
Restrict API access - Use n8n's API key permissions
Monitor logs - Check server logs for suspicious activity

Troubleshooting

Server won't start

# Check Node.js version
node --version  # Should be >= 18.0.0

# Verify environment variables
cat .env

# Check TypeScript compilation
npm run build

Workflow not found

Verify the workflow name matches exactly (case-sensitive)
Ensure the workflow is active in n8n
Check API key has permission to access workflows

Authentication failed

Verify N8N_API_KEY is correct
Check N8N_BASE_URL includes protocol (https://)
Ensure API key hasn't expired

Webhook trigger fails

Verify webhook node exists in workflow
Check webhook path matches workflow ID
Confirm N8N_WEBHOOK_SECRET if required

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT License - see LICENSE file for details.

Acknowledgments

Built with Model Context Protocol SDK
Powered by n8n workflow automation
Type validation by Zod

Support

🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions
📖 Documentation: Full API Reference

---

Built with the Model Context Protocol

careflow-mcp