Content
# Zulip MCP Server
A Model Context Protocol (MCP) server that exposes Zulip REST API capabilities as tools for LLMs. This server allows AI assistants to interact with your Zulip workspace programmatically.
## Features
### 🔄 **Resources** (Contextual Data)
- **User Directory**: Browse organization members with roles and status
- **Stream Directory**: Explore available streams and permissions
- **Message Formatting Guide**: Complete Zulip markdown syntax reference
- **Organization Info**: Server settings, policies, and custom emoji
- **User Groups**: Available groups for mentions and permissions
### 🛠️ **Tools** (25 Available Actions)
#### Helper Tools (LLM-Friendly Discovery)
- `search-users` - Find users by name/email before sending DMs
- `get-started` - Test connection and get workspace overview
#### Message Operations
- `send-message` - Send to streams or direct messages
- `get-messages` - Retrieve with advanced filtering and search
- `get-message` - Get detailed information about specific message
- `upload-file` - Share files and images
- `edit-message` - Modify content or move topics
- `delete-message` - Remove messages (admin permissions required)
- `get-message-read-receipts` - Check who read messages
- `add-emoji-reaction` - React with Unicode or custom emoji
- `remove-emoji-reaction` - Remove emoji reactions from messages
#### Scheduled Messages & Drafts
- `create-scheduled-message` - Schedule future messages
- `edit-scheduled-message` - Modify scheduled messages
- `create-draft` - Create new message drafts
- `get-drafts` - Retrieve saved drafts
- `edit-draft` - Update draft content
#### Stream Management
- `get-subscribed-streams` - List user's stream subscriptions
- `get-stream-id` - Get stream ID by name
- `get-stream-by-id` - Detailed stream information
- `get-topics-in-stream` - Browse recent topics
#### User Operations
- `get-users` - List organization members
- `get-user-by-email` - Find users by email
- `get-user` - Get detailed user information by ID
- `update-status` - Set status message and availability
- `get-user-groups` - List available user groups
## 📝 Zulip Terminology: Streams vs Channels
In Zulip, **"streams"** and **"channels"** refer to the same concept:
- **Stream** = Official Zulip terminology (used in API, tools, interface)
- **Channel** = Common term from Slack/Discord/Teams
- **Same thing** = Conversation spaces where teams discuss topics
This MCP server uses "stream" to match Zulip's official documentation and API.
## Installation & Setup
### Prerequisites
- Node.js 18+ with npm
- TypeScript 5+
- Access to a Zulip instance (e.g., https://your-organization.zulipchat.com)
- Zulip API credentials (bot token or API key)
### Quick Start
1. **Clone and install dependencies:**
```bash
git clone <repository-url>
cd zulip-mcp-server
npm install
```
2. **Configure environment variables:**
```bash
cp .env.example .env
# Edit .env with your Zulip credentials
```
3. **Build and run:**
```bash
npm run build
npm start
```
### Environment Configuration
Create a `.env` file with your Zulip credentials:
```env
ZULIP_URL=https://your-organization.zulipchat.com
ZULIP_EMAIL=your-bot-email@yourcompany.com
ZULIP_API_KEY=your-api-key-here
NODE_ENV=production
```
#### Getting Zulip API Credentials
1. **For Bot Access** (Recommended):
- Go to your Zulip organization settings
- Navigate to "Bots" section
- Create a new bot or use existing one
- Copy the bot email and API key
2. **For Personal Access**:
- Go to Personal Settings → Account & Privacy
- Find "API key" section
- Generate or reveal your API key
### Claude Desktop Integration
To use this MCP server with Claude Desktop, add the following configuration to your Claude Desktop config file:
#### Option 1: Using Environment Variables (Recommended)
Add to your Claude Desktop configuration:
```json
{
"mcpServers": {
"zulip": {
"command": "node",
"args": ["/path/to/zulip-mcp-server/dist/server.js"],
"env": {
"ZULIP_URL": "https://your-organization.zulipchat.com",
"ZULIP_EMAIL": "your-bot-email@yourcompany.com",
"ZULIP_API_KEY": "your-api-key-here"
}
}
}
}
```
#### Option 2: Using .env File
If you prefer using a `.env` file, ensure it's in the project directory and use:
```json
{
"mcpServers": {
"zulip": {
"command": "node",
"args": ["/path/to/zulip-mcp-server/dist/server.js"],
"cwd": "/path/to/zulip-mcp-server"
}
}
}
```
**Claude Desktop Config Location:**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
### Cursor Integration
To use this MCP server with Cursor IDE, add the following to your Cursor MCP settings:
#### Cursor MCP Configuration
Add to Cursor's MCP settings file (`.cursor-mcp/config.json` in your workspace or global settings):
```json
{
"mcpServers": {
"zulip": {
"command": "node",
"args": ["/path/to/zulip-mcp-server/dist/server.js"],
"env": {
"ZULIP_URL": "https://your-organization.zulipchat.com",
"ZULIP_EMAIL": "your-bot-email@yourcompany.com",
"ZULIP_API_KEY": "your-api-key-here"
},
"capabilities": {
"tools": true,
"resources": true
}
}
}
}
```
**Cursor MCP Config Location:**
- **Workspace**: `.cursor-mcp/config.json` in your project root
- **Global**: Platform-specific Cursor settings directory
### Raycast MCP Extension
To use this MCP server with Raycast, configure it in the MCP extension settings:
#### Raycast MCP Configuration
Add to Raycast MCP extension configuration:
```json
{
"servers": {
"zulip": {
"name": "Zulip Integration",
"description": "Send messages and interact with Zulip workspace",
"command": "node",
"args": ["/path/to/zulip-mcp-server/dist/server.js"],
"env": {
"ZULIP_URL": "https://your-organization.zulipchat.com",
"ZULIP_EMAIL": "your-bot-email@yourcompany.com",
"ZULIP_API_KEY": "your-api-key-here"
},
"icon": "💬",
"categories": ["communication", "productivity"]
}
}
}
```
**Raycast Setup Steps:**
1. Install the Raycast MCP extension
2. Open Raycast preferences → Extensions → MCP
3. Add new server configuration
4. Paste the JSON configuration above
5. Update paths and credentials accordingly
**Raycast Usage:**
- Use `⌘ + Space` to open Raycast
- Search for "Zulip" commands
- Execute MCP tools directly from Raycast interface
### Supported MCP Clients
This server is compatible with any MCP-compliant client. Here are the verified integrations:
| Platform | Config Type | Status | Usage |
|----------|-------------|---------|-------|
| **Claude Desktop** | JSON config | ✅ Verified | AI conversations with Zulip integration |
| **Cursor IDE** | Workspace/Global config | ✅ Verified | Code editor with Zulip notifications |
| **Raycast** | Extension config | ✅ Verified | Quick commands and automation |
| **Other MCP Clients** | Standard MCP protocol | 🔄 Compatible | Any MCP-compliant application |
**Universal MCP Command:**
```bash
node /path/to/zulip-mcp-server/dist/server.js
```
## Development
### Scripts
```bash
npm run dev # Development with hot reload
npm run build # Build for production
npm test # Run tests
npm run lint # Lint TypeScript
npm run typecheck # Type checking
```
### Project Structure
```
src/
├── server.ts # Main MCP server
├── zulip/
│ └── client.ts # Zulip API client
└── types.ts # TypeScript definitions
```
### Testing
Test the server using MCP Inspector:
```bash
npx @modelcontextprotocol/inspector npm start
```
## Usage Examples
### Sending Messages
```typescript
// Send to a stream
await callTool("send-message", {
type: "stream",
to: "general",
topic: "Daily Standup",
content: "Good morning team! 👋\n\n**Today's Goals:**\n- Review PR #123\n- Deploy feature X"
});
// Direct message
await callTool("send-message", {
type: "direct",
to: "user@example.com",
content: "Hey! Can you review the latest changes when you have a moment?"
});
```
### Getting Messages
```typescript
// Get recent messages from a stream
await callTool("get-messages", {
narrow: [["stream", "general"], ["topic", "announcements"]],
num_before: 50
});
// Search messages
await callTool("get-messages", {
narrow: [["search", "deployment"], ["sender", "admin@example.com"]]
});
```
### Stream Management
```typescript
// List subscribed streams
await callTool("get-subscribed-streams", {
include_subscribers: true
});
// Get stream topics
await callTool("get-topics-in-stream", {
stream_id: 123
});
```
## Markdown Formatting Support
The server includes a comprehensive formatting guide resource. Zulip supports:
- **Standard Markdown**: Bold, italic, code, links, lists
- **Mentions**: `@**Full Name**` (notify), `@_**Name**_` (silent)
- **Stream Links**: `#**stream-name**`
- **Code Blocks**: With syntax highlighting
- **Math**: LaTeX expressions with `$$math$$`
- **Spoilers**: `||hidden content||`
- **Custom Emoji**: Organization-specific emoji
## Error Handling
The server provides comprehensive error handling:
- Network connectivity issues
- Authentication failures
- Permission errors
- Rate limiting
- Invalid parameters
- Zulip API errors
All errors include helpful messages for debugging.
## Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure TypeScript compilation passes
5. Submit a pull request
## Support
For issues and questions:
- Check Zulip API documentation: https://zulip.com/api/
- Review MCP specification: https://modelcontextprotocol.io/
- Open GitHub issues for bugs or feature requests
Connection Info
You Might Also Like
No recommendations available