trycourier/courier-mcp
The official Model Context Protocol server for the Courier notification API. It gives AI agents full access to the Courier API β send messages, manage profiles, debug deliveries, configure lists, and more β through 60 tools backed by the @trycourier/courier Node SDK.
Installation
npx courier-mcpAsk AI about trycourier/courier-mcp
Powered by Claude Β· Grounded in docs
I know everything about trycourier/courier-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Courier MCP Server
The official Model Context Protocol (MCP) server for the Courier notification API. It gives AI agents full access to the Courier API β send messages, manage profiles, debug deliveries, configure lists, and more β through 60 tools backed by the @trycourier/courier Node SDK.
Install
Hosted (recommended)
Courier runs a hosted MCP server at https://mcp.courier.com. No local setup required.
Cursor β add to .cursor/mcp.json:
{
"mcpServers": {
"Courier": {
"url": "https://mcp.courier.com",
"headers": {
"api_key": "YOUR_COURIER_API_KEY"
}
}
}
}
Claude Code:
claude mcp add Courier --transport http --url https://mcp.courier.com --header "api_key: YOUR_COURIER_API_KEY"
Claude Desktop β add to claude_desktop_config.json:
{
"mcpServers": {
"Courier": {
"url": "https://mcp.courier.com",
"headers": {
"api_key": "YOUR_COURIER_API_KEY"
}
}
}
}
Local development
git clone https://github.com/trycourier/courier-mcp.git
cd courier-mcp
sh dev.sh
Then point your IDE at http://localhost:3000 with the same config format above.
Tools
59 default tools organized by API resource, plus 1 diagnostic tool available in local installs.
Default tools
| Category | Tools |
|---|---|
| Send | send_message, send_message_template, send_message_to_list, send_message_to_list_template |
| Messages | list_messages, get_message, get_message_content, get_message_history, cancel_message |
| Profiles | get_user_profile_by_id, create_or_merge_user, replace_profile, delete_profile, get_user_list_subscriptions, subscribe_user_to_lists, delete_user_list_subscriptions |
| Lists | list_lists, get_list, get_list_subscribers, create_list, subscribe_user_to_list, unsubscribe_user_from_list |
| Audiences | get_audience, list_audience_members, list_audiences, update_audience, delete_audience |
| Notifications | list_notifications, get_notification_content, get_notification_draft_content |
| Brands | create_brand, get_brand, list_brands |
| Auth | generate_jwt_for_user |
| User Tokens | list_user_push_tokens, get_user_push_token, create_or_replace_user_push_token |
| Docs | courier_installation_guide |
| Automations | invoke_automation_template, invoke_ad_hoc_automation |
| Bulk | create_bulk_job, add_bulk_users, run_bulk_job, get_bulk_job, list_bulk_users |
| Audit Events | get_audit_event, list_audit_events |
| Inbound | track_inbound_event |
| Tenants | get_tenant, create_or_update_tenant, list_tenants, delete_tenant |
| Users | get_user_preferences, update_user_preference_topic, list_user_tenants, add_user_to_tenant, remove_user_from_tenant |
| Translations | get_translation, update_translation |
Diagnostic tools (local only)
| Category | Tools |
|---|---|
| Config | get_environment_config β check which API key, base URL, and package version the MCP session is using |
Safer defaults (optional client policies)
Tools that send live traffic, carry destructiveHint in MCP annotations, or mutate provider integrations are listed in code as RECOMMENDED_CLIENT_DISABLED_TOOLS (source). Export it from @trycourier/courier-mcp if you want to drive codegen or docs. Teams typically paste subsets into Claude Code (permissions.deny / mcp__<serverName>__<toolName>) or Codex ([mcp_servers.<name>.disabled_tools] in config.toml). This does not change hosted MCP behavior until each client applies its own policy.
Architecture
courier-mcp/
βββ mcp/ # MCP package (@trycourier/courier-mcp on npm)
β βββ src/
β βββ index.ts # CourierMcp server class
β βββ policy/ # Optional client policy helpers (e.g. recommended disable list)
β βββ tools/ # Tool definitions (one file per API resource)
β βββ utils/ # Config, error handling, registry
βββ server/ # Express server (hosts the MCP package via HTTP)
β βββ src/index.ts # Stateless HTTP handler
βββ dev.sh # Local development launcher
The MCP package uses the official @trycourier/courier Node SDK (Stainless-generated) for all API calls. The SDK stays in sync with the Courier API spec automatically, so tool implementations are thin wrappers with proper error handling.
Configuration
| Header | Required | Description |
|---|---|---|
api_key | Yes | Your Courier API key. Get one at app.courier.com/settings/api-keys. |
base_url | No | Override the API base URL. Defaults to https://api.courier.com. |
Development
# Install dependencies
cd mcp && npm install && cd ../server && npm install && cd ..
# Start development server
sh dev.sh
# Run tests
cd mcp && npm test
# Build
cd mcp && npm run build
SDK dependency updates
The @trycourier/courier SDK dependency in mcp/ is updated automatically via Dependabot. Dependabot checks npm daily and opens a PR when a new SDK version is available.
- Patch/minor bumps: review CI status, then merge.
- Major bumps (labeled
breaking-review): check whether any tool input schemas or error handling need updates before merging.
After merging a Dependabot PR, the full pipeline runs automatically:
auto-version-bump.ymlbumps the MCP package patch version and pushes to main.publish-npm.ymlpublishes the new version to npm.bump-services.ymlopens a PR intrycourier/servicesto update the hosted MCP server.
Secrets required (set in repo Settings > Secrets and variables > Actions):
REPO_TOKENβ PAT withContents: Read and writeon this repo. Used byauto-version-bump.ymlto push to main and trigger downstream workflows.SERVICES_REPO_TOKENβ PAT withContents: Read and write+Pull requests: Read and writeontrycourier/services. Used bybump-services.ymlto open dependency bump PRs.NPM_TOKENβ npm publish token. Used bypublish-npm.yml.
