Superchat MCP

An unofficial MCP server that connects Claude Desktop and other local MCP clients to the public Superchat API.

Search contacts, inspect their cross-channel conversations, manage contact-list membership, review message history when Enterprise access is available, and send messages using your own Superchat API key. Each user runs their own process. No hosted service, account with this project, or database is required.

This project is not affiliated with, endorsed by, or supported by Superchat.

Quick start with Claude Desktop

Requires Node.js 22+, npm, and a Superchat workspace with API access.

From a checkout of this repository:

npm ci
npm run build

Create and name an API key in Superchat under Settings → Integrations → Explore; scroll to the API key area. See Superchat authentication.

On macOS, save the key in Keychain from your own Terminal. The prompt hides your input; the key is not part of the command, Claude config, or server environment:

node /absolute/path/to/superchat-mcp/dist/cli.js login

Do not paste the API key into an AI chat. login is interactive and refuses to run without a terminal. On other systems, use the SUPERCHAT_API_KEY environment variable as a fallback.

Open Claude Desktop's Settings → Developer → Edit Config and merge this entry into claude_desktop_config.json:

{
  "mcpServers": {
    "superchat": {
      "command": "node",
      "args": ["/absolute/path/to/superchat-mcp/dist/cli.js"],
      "env": {
        "SUPERCHAT_ENABLE_WRITES": "false",
        "SUPERCHAT_ENABLE_DELETES": "false"
      }
    }
  }
}

Replace the absolute path, then fully quit and reopen Claude Desktop. On macOS, run login first and remove any old SUPERCHAT_API_KEY entry from the config. If Claude cannot find node, set command to its absolute executable path. On non-macOS systems, configure SUPERCHAT_API_KEY through the client's environment settings. An editable example is in examples/claude-desktop.json.

Use node /path/to/superchat-mcp/dist/cli.js status to see which credential source is active without showing the key. Use node /path/to/superchat-mcp/dist/cli.js logout to remove the saved macOS Keychain entry. The first Keychain access may prompt macOS to allow the security utility to read it.

This is a local stdio integration. Add it through the desktop application's developer configuration, not a remote connector URL. The official MCP local-server guide explains the connection model.

Try:

Find the contact with email jane@example.com and show their conversations and internal notes.

List our WhatsApp channels and the templates available for a channel. Do not send anything yet.

Enable writes

Reading is enabled by default. To create/update contacts, change conversations, add notes, create exports, or send messages, add this to the server's env configuration and restart the client:

"SUPERCHAT_ENABLE_WRITES": "true"

Deletion requires both write access and:

"SUPERCHAT_ENABLE_DELETES": "true"

Disabled tools are not registered and cannot be called directly. Tool annotations also tell the client which actions write or delete data; the client remains responsible for its user-approval experience. Enabling writes is not blanket permission for the assistant to send messages.

Related MCP server: sendpilot-actions

Available tools

There are 27 read tools by default, including the Enterprise-only conversation-message history endpoint, 11 optional write tools, and 4 optional delete tools. Every tool name starts with superchat_.

The resource superchat://guide explains discovery, safe update semantics, messaging windows, pagination and exports to the assistant.

Superchat assigns each person a contact ID and can associate that contact with conversations on several channels. A conversation is one thread on one channel. Contact lists group contacts for segmentation and campaigns; labels organize conversations. list_contact_lists and get_contact_list return list metadata (ID, name and URL), not its participants. Use list_contact_lists_for_contact to see a specific contact's memberships, add_contact_to_contact_list to add membership, and remove_contact_from_contact_list to remove membership without deleting either the contact or the list.

list_conversation_messages is registered by default because only Superchat can determine whether the configured workspace/API key has Enterprise access. When message content or timestamps matter, call it for the relevant conversation rather than estimating dates from conversation metadata. If the API returns 403, report that message-history access is unavailable and recommend contacting Superchat Support to request access. No local Enterprise setting or restart is needed.

API behavior and limits

• Pagination: list calls return one page (25 records by default, up to 100). The Enterprise message-history endpoint defaults to 20. Pass the returned pagination.next_cursor as after, or previous_cursor as before. The server never silently downloads every page or follows API-provided URLs.

• Contact search: exactly one equality expression for mail, phone, instagram, or custom_attribute. Custom attributes require an identifier. There is no fuzzy name search in this wrapper.

• Contact handles: a person may have handles on several channels, but the public create/update contact schema lets API clients set email and phone handles. Platform-owned IDs such as Instagram or Messenger IDs are assigned by those platforms. Superchat generates the contact ID.

• Contact lists: list/get endpoints expose list metadata only, not list members. Membership is inspected per contact and can be added or removed separately; removing membership does not delete the contact or list.

• Conversation lookup: list_contact_conversations returns the contact's conversation threads and their metadata across channels. get_conversation reads one thread's metadata; neither returns messages.

• Contact updates: the documented schema requires first_name, last_name, and gender. Read the contact and preserve values you want to keep; explicit null clears these fields. Supplied handles and custom_attributes replace the entire lists. Omit them to leave them unchanged.

• Conversation updates: assigned_users and labels specify complete lists. An empty array clears the list. Conversation status and the channel's messaging time_window are separate concepts.

• Sending: uses one recipient identifier plus channel_id, not conversation_id. in_reply_to is a message ID. Check WhatsApp template approval, channel and variables before sending. Successful submission is not proof of delivery.

• Message history: list_conversation_messages uses a documented, Enterprise-only endpoint and is registered by default so a real request can discover the workspace/API key's access. A 403 includes a recommendation to contact Superchat Support to request access. The paginated result contains inbound/outbound messages with timestamps and supports optional created_after and created_before ISO 8601 filters. It is separate from internal notes. Conversation exports also return an asynchronous job's download link; they do not download or parse it.

• Media: sending uses already uploaded file IDs. Local file upload and downloads are outside this version's scope.

• Other endpoints: webhook administration, template creation, custom attribute administration, analytics and interactive WhatsApp message types are not implemented in this version. This is a curated integration, not full API coverage.

The API uses X-API-KEY against https://api.superchat.com/v1.0. The documented rate limit is 2,500 requests per workspace per five minutes, shared across its API keys.

GET requests retry network failures and HTTP 429/502/503/504 up to the configured limit, within a total request deadline. Retry-After is respected; waits over 30 seconds are returned to the client instead of retrying early. Writes are never automatically retried, including POST contact search. After a timed-out send, verify its outcome before repeating it. Responses larger than 5 MiB are rejected.

Configuration

On macOS, superchat-mcp login saves the API key in Keychain and the server reads it at startup before checking SUPERCHAT_API_KEY. superchat-mcp status reports only the source; superchat-mcp logout removes the Keychain entry. Other systems and CI can continue to use SUPERCHAT_API_KEY. Set SUPERCHAT_DISABLE_KEYCHAIN=true to use only the environment variable, including for credential-free discovery on a Mac with a saved key. Boolean settings accept only true or false. Invalid configuration fails startup. Restart the MCP process after changing settings.

Without an API key the server can start, advertise its tools and return the guide. API calls then return a MISSING_API_KEY tool error. This permits credential-free discovery and registry inspection.

For non-macOS or CI terminal development, copy .env.example to .env, fill it locally, and explicitly load it:

node --env-file=.env dist/cli.js

The server command waits for MCP input; it is not an interactive terminal application. It does not implicitly load .env from an arbitrary working directory. Use login, logout, or status directly in your terminal; never pass the API key as a command argument.

Data handling

The server does not persist API responses, log message content, or send telemetry. It passes selected results to the connected MCP client, which may send them to its model provider. Configure that client according to your organization's requirements.

Keep API keys out of source control, command arguments, and AI chats. On macOS, the Keychain is checked before the environment fallback, so remove any old key from the MCP client's env block after running login. The key is read by a local security subprocess and is never included in MCP tool calls or logged by this server. Superchat keys currently grant global read/write access; this server's local tool gates do not change the key's upstream permissions. API errors redact the configured key. Redirects and arbitrary request URLs are rejected. Returned contact, note and template text is treated as untrusted content, not instructions.

Development

npm ci
npm run check
npm run dev

check runs formatting, strict TypeScript checks, offline tests and a production build. Tests cover the HTTP client, access gates, request schemas, cursor validation, errors, and compiled stdio startup using both legacy and current MCP clients. They never access a real Superchat workspace or send customer messages.

The saved public API contract records source URLs and the retrieval date. Every tool's representative request is validated against it. See docs/api-contract.md for provenance and maintenance.

src/
  cli.ts                 stdio entry point
  credentials.ts         Keychain lookup and environment fallback
  server.ts              transport-independent server factory
  config.ts              environment validation
  client.ts              authenticated HTTP client, deadlines, retries, errors
  guide.ts               assistant-readable workflow guide
  tools/                 catalogs, contacts, conversations, messages
test/                    unit, protocol, CLI and public-contract tests
examples/                Claude Desktop configuration

Packaging and publication

This checkout is ready to build and package locally; it has not been published to npm as part of its creation. Do not assume an existing registry package with the same name belongs to this project.

npm run check
npm pack --dry-run
npm pack

The tarball contains the compiled server and documentation. Maintainers should set the final npm name, repository URL and ownership before publishing. Once released under that verified name, clients can use npx instead of a checkout path. No publishing credentials or automatic release workflow are included.

License

MIT. Superchat is a trademark of its respective owner.