novu-mcp-server/README.md

# Novu MCP Server

An MCP (Model Context Protocol) server that provides full coverage of the [Novu](https://novu.co) notification infrastructure API. Enables LLMs to manage subscribers, trigger notifications, configure workflows, and more through 78 tools across 11 API domains.

## Features

- **Full API coverage**: 78 tools spanning Events, Subscribers, Topics, Workflows, Notifications, Messages, Integrations, Environments, Translations, Contexts, and Channels
- **Dual transport**: stdio (for local use with Claude Code, OpenCode, etc.) and Streamable HTTP (for remote/multi-client use)
- **Pagination support**: Offset-based (v1) and cursor-based (v2) pagination
- **Error handling**: Actionable error messages with HTTP status-specific guidance
- **Response truncation**: Automatic truncation of large responses with pagination hints

## Prerequisites

- Node.js >= 18
- A Novu account and API key ([get one here](https://dashboard.novu.co))

## Installation

```bash
git clone <this-repo>
cd novu-mcp-server
npm install
npm run build
```

## Configuration

| Environment Variable | Required | Default | Description |
|---------------------|----------|---------|-------------|
| `NOVU_SECRET_KEY` | Yes | - | Your Novu API key from the dashboard |
| `NOVU_API_URL` | No | `https://api.novu.co` | API base URL. Use `https://eu.api.novu.co` for EU region |
| `TRANSPORT` | No | `stdio` | Transport mode: `stdio` or `http` |
| `PORT` | No | `3000` | HTTP server port (only used when TRANSPORT=http) |

## Usage

### With Claude Code / OpenCode (stdio)

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "novu": {
      "command": "node",
      "args": ["/path/to/novu-mcp-server/dist/index.js"],
      "env": {
        "NOVU_SECRET_KEY": "your-api-key-here"
      }
    }
  }
}
```

### With HTTP transport

```bash
NOVU_SECRET_KEY=your-key TRANSPORT=http PORT=3000 node dist/index.js
```

Then connect your MCP client to `http://localhost:3000/mcp`.

## Available Tools (78)

### Events (4 tools)
| Tool | Description |
|------|-------------|
| `novu_trigger_event` | Trigger a notification workflow for specific subscribers |
| `novu_bulk_trigger_event` | Trigger multiple notification events in a single request (max 100) |
| `novu_broadcast_event` | Broadcast a notification to all subscribers |
| `novu_cancel_event` | Cancel a pending triggered event by transaction ID |

### Subscribers (17 tools)
| Tool | Description |
|------|-------------|
| `novu_create_subscriber` | Create a new subscriber (upserts if exists) |
| `novu_get_subscriber` | Retrieve a subscriber by ID |
| `novu_update_subscriber` | Update subscriber attributes |
| `novu_delete_subscriber` | Delete a subscriber |
| `novu_search_subscribers` | Search/list subscribers with filters |
| `novu_bulk_create_subscribers` | Create multiple subscribers at once |
| `novu_get_subscriber_preferences` | Get notification preferences for a subscriber |
| `novu_update_subscriber_preferences` | Update notification preferences |
| `novu_bulk_update_subscriber_preferences` | Bulk update preferences |
| `novu_get_subscriber_subscriptions` | Get topic subscriptions for a subscriber |
| `novu_get_subscriber_notifications` | List notifications for a subscriber |
| `novu_update_notification_state` | Mark specific notifications as read/seen/etc |
| `novu_update_all_notification_states` | Mark all notifications as read/seen/etc |
| `novu_update_subscriber_online_status` | Set subscriber online/offline status |
| `novu_update_provider_credentials` | Update push/chat provider credentials |
| `novu_upsert_provider_credentials` | Upsert push/chat provider credentials |
| `novu_delete_provider_credentials` | Delete provider credentials |

### Topics (11 tools)
| Tool | Description |
|------|-------------|
| `novu_create_topic` | Create a new topic |
| `novu_get_topic` | Retrieve a topic by key |
| `novu_update_topic` | Update a topic's name |
| `novu_delete_topic` | Delete a topic |
| `novu_list_topics` | List all topics (cursor-based pagination) |
| `novu_create_topic_subscriptions` | Subscribe subscribers to a topic |
| `novu_delete_topic_subscriptions` | Unsubscribe subscribers from a topic |
| `novu_update_topic_subscription` | Update a topic subscription |
| `novu_list_topic_subscriptions` | List subscribers of a topic |
| `novu_check_topic_subscriber` | Check if a subscriber belongs to a topic |
| `novu_get_topic_subscription` | Get subscription details |

### Workflows (7 tools)
| Tool | Description |
|------|-------------|
| `novu_create_workflow` | Create a new notification workflow |
| `novu_get_workflow` | Retrieve a workflow by ID |
| `novu_update_workflow` | Update a workflow |
| `novu_delete_workflow` | Delete a workflow |
| `novu_list_workflows` | List all workflows |
| `novu_sync_workflow` | Sync a workflow between environments |
| `novu_get_workflow_step` | Get details of a specific workflow step |

### Notifications (2 tools)
| Tool | Description |
|------|-------------|
| `novu_list_notification_events` | List notification events with filters |
| `novu_get_notification_event` | Get detailed notification event with execution logs |

### Messages (3 tools)
| Tool | Description |
|------|-------------|
| `novu_list_messages` | List messages with filters |
| `novu_delete_message` | Delete a specific message |
| `novu_delete_messages_by_transaction` | Delete all messages for a transaction |

### Integrations (7 tools)
| Tool | Description |
|------|-------------|
| `novu_list_integrations` | List all integrations |
| `novu_list_active_integrations` | List only active integrations |
| `novu_create_integration` | Create a new provider integration |
| `novu_update_integration` | Update an integration |
| `novu_delete_integration` | Delete an integration |
| `novu_set_primary_integration` | Set an integration as primary for its channel |
| `novu_generate_chat_oauth_url` | Generate OAuth URL for chat integrations |

### Environments (5 tools)
| Tool | Description |
|------|-------------|
| `novu_list_environments` | List all environments |
| `novu_create_environment` | Create a new environment |
| `novu_update_environment` | Update an environment |
| `novu_delete_environment` | Delete an environment |
| `novu_list_environment_tags` | List tags across environments |

### Translations (7 tools)
| Tool | Description |
|------|-------------|
| `novu_create_translation` | Create a translation |
| `novu_get_translation` | Retrieve a translation |
| `novu_delete_translation` | Delete a translation |
| `novu_get_translation_group` | Get a translation group |
| `novu_delete_translation_group` | Delete a translation group |
| `novu_import_master_translations` | Import master translation JSON |
| `novu_get_master_translations` | Get master translations JSON |

### Contexts (5 tools)
| Tool | Description |
|------|-------------|
| `novu_list_contexts` | List all contexts |
| `novu_create_context` | Create a new context |
| `novu_get_context` | Retrieve a context |
| `novu_update_context` | Update a context |
| `novu_delete_context` | Delete a context |

### Channels (10 tools)
| Tool | Description |
|------|-------------|
| `novu_list_channel_connections` | List channel connections |
| `novu_create_channel_connection` | Create a channel connection |
| `novu_get_channel_connection` | Get a channel connection |
| `novu_update_channel_connection` | Update a channel connection |
| `novu_delete_channel_connection` | Delete a channel connection |
| `novu_list_channel_endpoints` | List channel endpoints |
| `novu_create_channel_endpoint` | Create a channel endpoint |
| `novu_get_channel_endpoint` | Get a channel endpoint |
| `novu_update_channel_endpoint` | Update a channel endpoint |
| `novu_delete_channel_endpoint` | Delete a channel endpoint |

## Development

```bash
# Watch mode with auto-reload
npm run dev

# Build
npm run build

# Test with MCP Inspector
NOVU_SECRET_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js
```

## License

MIT