zulip

This MCP server exposes Zulip REST API capabilities as LLM-friendly tools, enabling an AI assistant to interact with your Zulip workspace. It provides a suite of 25 tools for working with users, streams, messages, drafts, and scheduling, such as search-users, send-message, get-messages, create-draft, get-subscribed-streams, and many more. The server handles Zulip authentication via credentials supplied in environment variables, and tools return structured data or perform actions within your Zulip organization. You can invoke tools through your MCP client (Claude Desktop, Cursor, Raycast, etc.) by calling the tool name and providing the required parameters, and the server will translate those calls into Zulip API requests and return results suitable for further processing by the LLM.

Typical use cases include looking up users or streams, composing and sending messages to streams or direct messages, attaching files, managing reactions, scheduling messages, and retrieving message history with filters. The tooling is designed to align with Zulip’s terminology (streams) while still exposing the full range of Zulip API capabilities to your AI workflows. For best results, configure the required Zulip credentials (URL, bot email/API key) in a secure environment and reference the tools by their exact names when issuing commands to your MCP client.

Prerequisites:

• Node.js 18+ with npm installed
• TypeScript 5+ (for development and building)
• Access to a Zulip instance and Zulip API credentials (bot token or API key)

Installation steps:

1. Clone the repository and navigate to the project root:

git clone <repository-url>
cd zulip-mcp-server

2. Install dependencies:

npm install

3. Configure environment variables (example):

cp .env.example .env

Edit the .env file to include your Zulip credentials:

ZULIP_URL=https://your-organization.zulipchat.com
ZULIP_EMAIL=your-bot-email@yourcompany.com
ZULIP_API_KEY=your-api-key-here
NODE_ENV=production

4. Build the server (if applicable to your setup):

npm run build

5. Run the MCP server:

npm start

6. Verify accessibility:

• The MCP server should respond to MCP client requests and expose the Zulip tools via the configured endpoint.

Notes:

• Ensure the Zulip URL and credentials have the required permissions for the operations you plan to perform.
• If you’re integrating with Claude Desktop, Cursor, Raycast, or other clients, configure the respective client with the correct command and arguments as shown in the README.

Tips and common considerations:

• Keep Zulip API credentials secure and avoid exposing .env contents in public settings.
• When using admin-restricted actions (e.g., delete-message), ensure the credentials have the necessary permissions.
• Use descriptive topics and content when creating messages to improve traceability in conversations.
• If you upgrade Zulip API versions, review the client.ts wrapper for any breaking changes.
• The server can be wired into multiple MCP clients; maintain consistent environment configurations across integrations.
• For debugging, run the server in development mode and use MCP Inspector or similar tools to validate tool schemas and responses.