From 94d887ef3686d1a171d34d78072f10efc96e57cd Mon Sep 17 00:00:00 2001 From: "s.savinel" Date: Mon, 30 Mar 2026 13:59:32 +0200 Subject: [PATCH] docs: add README with setup, configuration, and tool reference --- README.md | 203 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..4bc5aa9 --- /dev/null +++ b/README.md @@ -0,0 +1,203 @@ +# 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 +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