Navigation: Home

Installation

API Reference

Usage Examples

Troubleshooting

Client Configuration Guide

Configure the Zulip MCP Server with your preferred LLM client. This guide covers the most popular integrations.

Overview

The Zulip MCP Server works with any MCP-compliant client. Here are verified configurations:

Client	Status	Use Case	Configuration
Claude Desktop	✅ Verified	AI conversations with Zulip	Setup →
Cursor IDE	✅ Verified	Code editor with Zulip notifications	Setup →
Raycast	✅ Verified	Quick commands and automation	Setup →
Other MCP Clients	🔄 Compatible	Any MCP-compliant application	Generic →

---

Claude Desktop

Configuration Location

Find your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Option 1: Environment Variables (Recommended)

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "zulip": {
      "command": "node",
      "args": ["/absolute/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: .env File

If you prefer using a .env file:

{
  "mcpServers": {
    "zulip": {
      "command": "node",
      "args": ["/absolute/path/to/zulip-mcp-server/dist/server.js"],
      "cwd": "/absolute/path/to/zulip-mcp-server"
    }
  }
}

Verification

1. Restart Claude Desktop after updating the configuration
2. Open a new conversation and ask: “Can you check if Zulip is connected?”
3. Look for Zulip tools in the tools panel (should show 25 tools available)

Example Usage in Claude

You: "Send a message to the #general stream saying hello to the team"

Claude: I'll send a message to the general stream for you. Let me use the send-message tool.

[Claude uses the send-message tool with appropriate parameters]

The message has been sent successfully to the general stream!

---

Cursor IDE

Configuration Location

Cursor supports both workspace and global MCP configurations:

• Workspace: .cursor-mcp/config.json in your project root
• Global: Platform-specific Cursor settings directory

Workspace Configuration

Create .cursor-mcp/config.json in your project:

{
  "mcpServers": {
    "zulip": {
      "command": "node",
      "args": ["/absolute/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
      }
    }
  }
}

Global Configuration

Add to Cursor’s global MCP settings:

{
  "mcpServers": {
    "zulip": {
      "name": "Zulip Integration",
      "description": "Send messages and interact with Zulip workspace",
      "command": "node",
      "args": ["/absolute/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
      }
    }
  }
}

Setup Steps

1. Create configuration file in your preferred location
2. Update file paths to match your installation
3. Add your Zulip credentials
4. Restart Cursor IDE
5. Open MCP panel to verify connection

Use Cases in Cursor

• Deployment notifications: Automatically notify team when code is deployed
• Code review requests: Send formatted messages about pull requests
• Error reporting: Forward build failures to development channels
• Status updates: Share development progress with stakeholders

---

Raycast

Installation

1. Install Raycast MCP Extension:
   • Open Raycast
   • Search for “MCP” extension
   • Install the official MCP extension
2. Configure Server:
   • Open Raycast preferences
   • Go to Extensions → MCP
   • Add new server configuration

Configuration

Add this configuration in the Raycast MCP extension:

{
  "servers": {
    "zulip": {
      "name": "Zulip Integration",
      "description": "Send messages and interact with Zulip workspace",
      "command": "node",
      "args": ["/absolute/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"],
      "capabilities": {
        "tools": true,
        "resources": true
      }
    }
  }
}

Usage

1. Open Raycast with ⌘ + Space (macOS) or Alt + Space (Windows/Linux)
2. Search for “Zulip” commands
3. Execute tools directly from the Raycast interface

Example Raycast Commands

• “Zulip send message to general”
• “Zulip get recent messages”
• “Zulip search users”
• “Zulip check connection”

---

Generic MCP Client

For any MCP-compliant client, use this universal configuration pattern:

Basic Setup

{
  "name": "zulip-mcp-server",
  "command": "node",
  "args": ["/absolute/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"
  }
}

Command Line Usage

You can also run the server directly:

# Set environment variables
export ZULIP_URL="https://your-org.zulipchat.com"
export ZULIP_EMAIL="bot@your-org.zulipchat.com"  
export ZULIP_API_KEY="your-api-key"

# Run the server
node /path/to/zulip-mcp-server/dist/server.js

---

Path Configuration

Finding Absolute Paths

Use these commands to get the correct paths for your configuration:

# Get the project directory
pwd
# Example output: /Users/username/zulip-mcp-server

# Verify the compiled server exists
ls -la dist/server.js
# Should show the compiled JavaScript file

# Test the server directly
node dist/server.js

Common Path Examples

macOS/Linux:

/Users/username/zulip-mcp-server/dist/server.js
/home/username/zulip-mcp-server/dist/server.js

Windows:

C:\Users\username\zulip-mcp-server\dist\server.js

---

Environment Variables vs .env Files

Environment Variables (Recommended for Production)

Pros:

• More secure (not stored in files)
• Better for containerized deployments
• Easier to manage in CI/CD

Setup:

export ZULIP_URL="https://your-org.zulipchat.com"
export ZULIP_EMAIL="bot@your-org.zulipchat.com"
export ZULIP_API_KEY="your-api-key"

.env Files (Good for Development)

Pros:

• Easy to manage locally
• Version control friendly (when properly excluded)
• Simple configuration

Setup:

# .env file in project root
ZULIP_URL=https://your-org.zulipchat.com
ZULIP_EMAIL=bot@your-org.zulipchat.com
ZULIP_API_KEY=your-api-key

---

Troubleshooting Configuration

Common Issues

“Server not found” or “Command failed”

• Check file paths: Ensure absolute paths are correct
• Verify build: Run npm run build to ensure dist/server.js exists
• Test directly: Run node dist/server.js to verify the server works

“Environment variables missing”

• Check credentials: Verify all required variables are set
• Test variables: Use echo $ZULIP_URL to check if set
• Restart client: Some clients need restart after config changes

“Connection failed”

• Verify credentials: Test with get-started tool
• Check network: Ensure Zulip URL is accessible
• Review permissions: Verify bot has necessary permissions

Debug Mode

Enable debug logging in any client:

{
  "env": {
    "ZULIP_URL": "https://your-org.zulipchat.com",
    "ZULIP_EMAIL": "bot@your-org.zulipchat.com",
    "ZULIP_API_KEY": "your-api-key",
    "DEBUG": "true"
  }
}

Verification Steps

1. Test direct execution:

   node dist/server.js
   

2. Use MCP Inspector:

   npx @modelcontextprotocol/inspector npm start
   

3. Try the get-started tool in your client to verify connection

---

Next Steps

After successful configuration:

1. Test basic functionality with the get-started tool
2. Explore available tools in the API Reference
3. Try practical examples from Usage Examples
4. Customize for your workflow based on your team’s needs

Need help with specific use cases? Check out our Usage Examples or Troubleshooting Guide.