novu-mcp-server/README.md

Novu MCP Server

An MCP (Model Context Protocol) server that provides full coverage of the Novu 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)

Installation

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:

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

With HTTP transport

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

# 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