{"_id":"@dmikushin/zulip-mcp-server","name":"@dmikushin/zulip-mcp-server","dist-tags":{"latest":"1.5.0"},"versions":{"1.5.0":{"name":"@dmikushin/zulip-mcp-server","version":"1.5.0","description":"MCP server that exposes Zulip REST API capabilities as tools for LLMs","main":"dist/server.js","type":"module","scripts":{"build":"npm run clean && tsc","build:watch":"tsc --watch","clean":"rm -rf dist","dev":"tsx src/server.ts","start":"node dist/server.js","test":"jest","lint":"eslint src/**/*.ts","lint:fix":"eslint src/**/*.ts --fix","typecheck":"tsc --noEmit","precommit":"npm run lint && npm run typecheck && npm run build","prepare":"npm run build","audit:fix":"npm audit fix","quality":"npm run lint && npm run typecheck && npm audit","quality-full":"npm run lint && npm run typecheck && npm run test && npm audit"},"keywords":["mcp","zulip","chat","api","llm","tools"],"author":{"name":"Dmitry Mikushin","email":"dmitry@kernelgen.org"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/dmikushin/zulip-mcp-server.git"},"homepage":"https://github.com/dmikushin/zulip-mcp-server#readme","bugs":{"url":"https://github.com/dmikushin/zulip-mcp-server/issues"},"publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","axios":"^1.6.0","dotenv":"^16.5.0","zod":"^3.22.4"},"devDependencies":{"@types/node":"^20.0.0","@typescript-eslint/eslint-plugin":"^6.0.0","@typescript-eslint/parser":"^6.0.0","eslint":"^8.0.0","jest":"^29.0.0","tsx":"^4.0.0","typescript":"^5.0.0"},"bin":{"zulip-mcp-server":"dist/server.js"},"_id":"@dmikushin/zulip-mcp-server@1.5.0","gitHead":"410081985938ebd3c9d147a75ad7596b2eab8bd6","types":"./dist/server.d.ts","_nodeVersion":"21.4.0","_npmVersion":"10.2.4","dist":{"integrity":"sha512-y1n0Duay7/olb27xbQ0t4yMtJSg/HRE5DmOKFkp8WcOagJ9YkPSzVBasuxOll2wNkh0ppqd8Ul4en6hbpevAfQ==","shasum":"b9c298d6255c516b99662b8a435a74830ff8feee","tarball":"https://registry.npmjs.org/@dmikushin/zulip-mcp-server/-/zulip-mcp-server-1.5.0.tgz","fileCount":14,"unpackedSize":146707,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHxJbK4paWYSBXUEka3is/jgBOUVtcrKMEILnDoM0B+AAiEAvROvH0YfqCSv1ZgfuscZX3zbbKFo0etOxBmdRPs0nDw="}]},"_npmUser":{"name":"dmikushin","email":"dmitry@kernelgen.org"},"directories":{},"maintainers":[{"name":"dmikushin","email":"dmitry@kernelgen.org"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/zulip-mcp-server_1.5.0_1761125809544_0.8482575173778588"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-22T09:36:49.420Z","1.5.0":"2025-10-22T09:36:49.773Z","modified":"2025-10-22T09:36:50.091Z"},"maintainers":[{"name":"dmikushin","email":"dmitry@kernelgen.org"}],"description":"MCP server that exposes Zulip REST API capabilities as tools for LLMs","homepage":"https://github.com/dmikushin/zulip-mcp-server#readme","keywords":["mcp","zulip","chat","api","llm","tools"],"repository":{"type":"git","url":"git+https://github.com/dmikushin/zulip-mcp-server.git"},"author":{"name":"Dmitry Mikushin","email":"dmitry@kernelgen.org"},"bugs":{"url":"https://github.com/dmikushin/zulip-mcp-server/issues"},"license":"MIT","readme":"# Zulip MCP Server\n\nA 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.\n\n## Features\n\n### 🔄 **Resources** (Contextual Data)\n- **User Directory**: Browse organization members with roles and status\n- **Stream Directory**: Explore available streams and permissions  \n- **Message Formatting Guide**: Complete Zulip markdown syntax reference\n- **Organization Info**: Server settings, policies, and custom emoji\n- **User Groups**: Available groups for mentions and permissions\n\n### 🛠️ **Tools** (25 Available Actions)\n\n#### Helper Tools (LLM-Friendly Discovery)\n- `search-users` - Find users by name/email before sending DMs\n- `get-started` - Test connection and get workspace overview\n\n#### Message Operations\n- `send-message` - Send to streams or direct messages\n- `get-messages` - Retrieve with advanced filtering and search\n- `get-message` - Get detailed information about specific message\n- `upload-file` - Share files and images\n- `edit-message` - Modify content or move topics\n- `delete-message` - Remove messages (admin permissions required)\n- `get-message-read-receipts` - Check who read messages\n- `add-emoji-reaction` - React with Unicode or custom emoji\n- `remove-emoji-reaction` - Remove emoji reactions from messages\n\n#### Scheduled Messages & Drafts\n- `create-scheduled-message` - Schedule future messages\n- `edit-scheduled-message` - Modify scheduled messages\n- `create-draft` - Create new message drafts\n- `get-drafts` - Retrieve saved drafts\n- `edit-draft` - Update draft content\n\n#### Stream Management\n- `get-subscribed-streams` - List user's stream subscriptions\n- `get-stream-id` - Get stream ID by name\n- `get-stream-by-id` - Detailed stream information\n- `get-topics-in-stream` - Browse recent topics\n\n#### User Operations\n- `get-users` - List organization members\n- `get-user-by-email` - Find users by email\n- `get-user` - Get detailed user information by ID\n- `update-status` - Set status message and availability\n- `get-user-groups` - List available user groups\n\n## 📝 Zulip Terminology: Streams vs Channels\n\nIn Zulip, **\"streams\"** and **\"channels\"** refer to the same concept:\n- **Stream** = Official Zulip terminology (used in API, tools, interface)\n- **Channel** = Common term from Slack/Discord/Teams  \n- **Same thing** = Conversation spaces where teams discuss topics\n\nThis MCP server uses \"stream\" to match Zulip's official documentation and API.\n\n## Installation & Setup\n\n### Prerequisites\n- Node.js 18+ with npm\n- TypeScript 5+\n- Access to a Zulip instance (e.g., https://your-organization.zulipchat.com)\n- Zulip API credentials (bot token or API key)\n\n### Quick Start\n\n1. **Clone and install dependencies:**\n```bash\ngit clone <repository-url>\ncd zulip-mcp-server\nnpm install\n```\n\n2. **Configure environment variables:**\n```bash\ncp .env.example .env\n# Edit .env with your Zulip credentials\n```\n\n3. **Build and run:**\n```bash\nnpm run build\nnpm start\n```\n\n### Environment Configuration\n\nCreate a `.env` file with your Zulip credentials:\n\n```env\nZULIP_URL=https://your-organization.zulipchat.com\nZULIP_EMAIL=your-bot-email@yourcompany.com\nZULIP_API_KEY=your-api-key-here\nNODE_ENV=production\n```\n\n#### Getting Zulip API Credentials\n\n1. **For Bot Access** (Recommended):\n   - Go to your Zulip organization settings\n   - Navigate to \"Bots\" section\n   - Create a new bot or use existing one\n   - Copy the bot email and API key\n\n2. **For Personal Access**:\n   - Go to Personal Settings → Account & Privacy\n   - Find \"API key\" section\n   - Generate or reveal your API key\n\n### Claude Desktop Integration\n\nTo use this MCP server with Claude Desktop, add the following configuration to your Claude Desktop config file:\n\n#### Option 1: Using Environment Variables (Recommended)\n\nAdd to your Claude Desktop configuration:\n```json\n{\n  \"mcpServers\": {\n    \"zulip\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/zulip-mcp-server/dist/server.js\"],\n      \"env\": {\n        \"ZULIP_URL\": \"https://your-organization.zulipchat.com\",\n        \"ZULIP_EMAIL\": \"your-bot-email@yourcompany.com\", \n        \"ZULIP_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n#### Option 2: Using .env File\n\nIf you prefer using a `.env` file, ensure it's in the project directory and use:\n```json\n{\n  \"mcpServers\": {\n    \"zulip\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/zulip-mcp-server/dist/server.js\"],\n      \"cwd\": \"/path/to/zulip-mcp-server\"\n    }\n  }\n}\n```\n\n**Claude Desktop Config Location:**\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n### Cursor Integration\n\nTo use this MCP server with Cursor IDE, add the following to your Cursor MCP settings:\n\n#### Cursor MCP Configuration\n\nAdd to Cursor's MCP settings file (`.cursor-mcp/config.json` in your workspace or global settings):\n\n```json\n{\n  \"mcpServers\": {\n    \"zulip\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/zulip-mcp-server/dist/server.js\"],\n      \"env\": {\n        \"ZULIP_URL\": \"https://your-organization.zulipchat.com\",\n        \"ZULIP_EMAIL\": \"your-bot-email@yourcompany.com\",\n        \"ZULIP_API_KEY\": \"your-api-key-here\"\n      },\n      \"capabilities\": {\n        \"tools\": true,\n        \"resources\": true\n      }\n    }\n  }\n}\n```\n\n**Cursor MCP Config Location:**\n- **Workspace**: `.cursor-mcp/config.json` in your project root\n- **Global**: Platform-specific Cursor settings directory\n\n### Raycast MCP Extension\n\nTo use this MCP server with Raycast, configure it in the MCP extension settings:\n\n#### Raycast MCP Configuration\n\nAdd to Raycast MCP extension configuration:\n\n```json\n{\n  \"servers\": {\n    \"zulip\": {\n      \"name\": \"Zulip Integration\",\n      \"description\": \"Send messages and interact with Zulip workspace\",\n      \"command\": \"node\",\n      \"args\": [\"/path/to/zulip-mcp-server/dist/server.js\"],\n      \"env\": {\n        \"ZULIP_URL\": \"https://your-organization.zulipchat.com\",\n        \"ZULIP_EMAIL\": \"your-bot-email@yourcompany.com\",\n        \"ZULIP_API_KEY\": \"your-api-key-here\"\n      },\n      \"icon\": \"💬\",\n      \"categories\": [\"communication\", \"productivity\"]\n    }\n  }\n}\n```\n\n**Raycast Setup Steps:**\n1. Install the Raycast MCP extension\n2. Open Raycast preferences → Extensions → MCP\n3. Add new server configuration\n4. Paste the JSON configuration above\n5. Update paths and credentials accordingly\n\n**Raycast Usage:**\n- Use `⌘ + Space` to open Raycast\n- Search for \"Zulip\" commands\n- Execute MCP tools directly from Raycast interface\n\n### Supported MCP Clients\n\nThis server is compatible with any MCP-compliant client. Here are the verified integrations:\n\n| Platform | Config Type | Status | Usage |\n|----------|-------------|---------|-------|\n| **Claude Desktop** | JSON config | ✅ Verified | AI conversations with Zulip integration |\n| **Cursor IDE** | Workspace/Global config | ✅ Verified | Code editor with Zulip notifications |\n| **Raycast** | Extension config | ✅ Verified | Quick commands and automation |\n| **Other MCP Clients** | Standard MCP protocol | 🔄 Compatible | Any MCP-compliant application |\n\n**Universal MCP Command:**\n```bash\nnode /path/to/zulip-mcp-server/dist/server.js\n```\n\n## Development\n\n### Scripts\n```bash\nnpm run dev          # Development with hot reload\nnpm run build        # Build for production\nnpm test            # Run tests\nnpm run lint        # Lint TypeScript\nnpm run typecheck   # Type checking\n```\n\n### Project Structure\n```\nsrc/\n├── server.ts        # Main MCP server\n├── zulip/\n│   └── client.ts    # Zulip API client\n└── types.ts         # TypeScript definitions\n```\n\n### Testing\n\nTest the server using MCP Inspector:\n```bash\nnpx @modelcontextprotocol/inspector npm start\n```\n\n## Usage Examples\n\n### Sending Messages\n```typescript\n// Send to a stream\nawait callTool(\"send-message\", {\n  type: \"stream\",\n  to: \"general\",\n  topic: \"Daily Standup\",\n  content: \"Good morning team! 👋\\n\\n**Today's Goals:**\\n- Review PR #123\\n- Deploy feature X\"\n});\n\n// Direct message\nawait callTool(\"send-message\", {\n  type: \"direct\",\n  to: \"user@example.com\",\n  content: \"Hey! Can you review the latest changes when you have a moment?\"\n});\n```\n\n### Getting Messages\n```typescript\n// Get recent messages from a stream\nawait callTool(\"get-messages\", {\n  narrow: [[\"stream\", \"general\"], [\"topic\", \"announcements\"]],\n  num_before: 50\n});\n\n// Search messages\nawait callTool(\"get-messages\", {\n  narrow: [[\"search\", \"deployment\"], [\"sender\", \"admin@example.com\"]]\n});\n```\n\n### Stream Management\n```typescript\n// List subscribed streams\nawait callTool(\"get-subscribed-streams\", {\n  include_subscribers: true\n});\n\n// Get stream topics\nawait callTool(\"get-topics-in-stream\", {\n  stream_id: 123\n});\n```\n\n## Markdown Formatting Support\n\nThe server includes a comprehensive formatting guide resource. Zulip supports:\n\n- **Standard Markdown**: Bold, italic, code, links, lists\n- **Mentions**: `@**Full Name**` (notify), `@_**Name**_` (silent)\n- **Stream Links**: `#**stream-name**`\n- **Code Blocks**: With syntax highlighting\n- **Math**: LaTeX expressions with `$$math$$`\n- **Spoilers**: `||hidden content||`\n- **Custom Emoji**: Organization-specific emoji\n\n## Error Handling\n\nThe server provides comprehensive error handling:\n- Network connectivity issues\n- Authentication failures\n- Permission errors\n- Rate limiting\n- Invalid parameters\n- Zulip API errors\n\nAll errors include helpful messages for debugging.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure TypeScript compilation passes\n5. Submit a pull request\n\n## Support\n\nFor issues and questions:\n- Check Zulip API documentation: https://zulip.com/api/\n- Review MCP specification: https://modelcontextprotocol.io/\n- Open GitHub issues for bugs or feature requests\n","readmeFilename":"README.md","_rev":"1-d59dba93dcfae93c74033139f15fe486"}