Zudello MCP Server

Model Context Protocol (MCP) server exposing 106 Zudello ERP automation tools for use with Claude Desktop, Claude Code CLI, and other MCP-compatible clients.

Features

• 106 Zudello Tools: Complete access to Zudello ERP operations
  • 65 read-only tools for data access and discovery
  • 41 write tools with approval metadata
• Multi-tenant Support: Environment-based authentication
• Approval Workflow: Write operations return approval metadata with risk levels
• Type-Safe: Full TypeScript implementation with strict types
• ESM Modules: Modern ES module architecture

Installation

Using npx (Recommended)

No installation required - use directly with npx:

npx @zudello/modelcontextprotocol

Global Installation

Install globally to use without npx prefix:

npm install -g @zudello/modelcontextprotocol

Quick Start

1. Get Your Zudello Credentials

You'll need the following from your Zudello account:

• ZUDELLO_TOKEN: JWT authentication token (starts with "eyJ")
• ZUDELLO_ORGANIZATION: Organization UUID (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
• ZUDELLO_TEAM: Team UUID (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
• ZUDELLO_CLUSTER_URL: Your region-specific API cluster
  • Examples: api.1.eur1.zudello.io (Europe), api.au.3.zudello.io (Australia), api.us.1.zudello.io (US)
  • Check your Zudello instance URL to determine your cluster

2. Configure Claude Desktop

Add the MCP server to your Claude Desktop configuration file:

macOS

File location: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux

File location: ~/.config/claude/claude_desktop_config.json

Windows

File location: %APPDATA%\Claude\claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "zudello": {
      "command": "npx",
      "args": ["@zudello/modelcontextprotocol"],
      "env": {
        "ZUDELLO_TOKEN": "your_jwt_token",
        "ZUDELLO_ORGANIZATION": "your_org_uuid",
        "ZUDELLO_TEAM": "your_team_uuid",
        "ZUDELLO_CLUSTER_URL": "api.1.eur1.zudello.io",
        "AUTHENTICATION_API_BASE": "api.1.global.zudello.io"
      }
    }
  }
}

3. Configure Claude Code CLI

Add the MCP server to your Claude Code configuration file:

macOS/Linux

File location: ~/.config/claude-code/mcp_servers.json

Windows

File location: %APPDATA%\claude-code\mcp_servers.json

Configuration:

{
  "mcpServers": {
    "zudello": {
      "command": "npx",
      "args": ["@zudello/modelcontextprotocol"],
      "env": {
        "ZUDELLO_TOKEN": "your_jwt_token",
        "ZUDELLO_ORGANIZATION": "your_org_uuid",
        "ZUDELLO_TEAM": "your_team_uuid",
        "ZUDELLO_CLUSTER_URL": "api.1.eur1.zudello.io",
        "AUTHENTICATION_API_BASE": "api.1.global.zudello.io"
      }
    }
  }
}

4. Restart Claude

Restart Claude Desktop or Claude Code CLI to load the new configuration.

5. Verify Installation

Ask Claude: "What Zudello MCP tools are available?"

You should see a list of 106 available tools.

Configuration Details

Environment Variables

• ZUDELLO_TOKEN (required): JWT authentication token from your Zudello account
• ZUDELLO_ORGANIZATION (required): Your organization UUID
• ZUDELLO_TEAM (required): Your team UUID
• ZUDELLO_CLUSTER_URL (optional): Region-specific API cluster (default: api.1.eur1.zudello.io)
• AUTHENTICATION_API_BASE (optional): Organization-level API endpoint (default: api.1.global.zudello.io)
• LOG_LEVEL (optional): Logging level - debug, info, warn, error (default: info)

API Endpoints

The MCP server uses two different API endpoints:

1. Team-Level API (ZUDELLO_CLUSTER_URL): Used for most operations (97 tools)

   • Region-specific endpoints for team data and operations
   • Examples: api.1.eur1.zudello.io, api.au.3.zudello.io, api.us.1.zudello.io

2. Organization-Level API (AUTHENTICATION_API_BASE): Used for org admin operations (9 tools)

   • Default: api.1.global.zudello.io
   • Global endpoint for cross-team operations (teams, users, groups)

Tool Categories (106 Total)

Core Operations (3 tools)

• zudelloSearch - Search and filter resources with complex queries
• zudelloFetch - Fetch single resource by UUID or external ID
• zudelloPushMessage - Load Zudello data into conversation context

Model Discovery (5 tools)

• zudelloListModels - List all available data models
• zudelloGetModelMetadata - Get display names, icons, UI metadata
• zudelloGetModelSchema - Get field definitions and types
• zudelloGetModelRelations - Discover relationships between models
• zudelloGetFieldMetadata - Get detailed field-level metadata

Configuration Management (5 tools)

• Read: zudelloGetConfig, zudelloListConfigs
• Write: zudelloCreateConfig, zudelloUpdateConfig, zudelloUpdateConfigsOrder

Resource Operations (2 tools)

• zudelloGetResources - Batch fetch multiple resources
• zudelloUpdateOrCreateResources - Upsert resources in batch

Automation Rules - Sentences (8 tools)

• Read: zudelloGetSentence, zudelloGetSentenceTemplate, zudelloListSentences, zudelloListSentenceTemplates, zudelloListSentenceResources
• Write: zudelloCreateSentence, zudelloUpdateSentence, zudelloUpdateSentencesOrder

Automation System (10 tools)

• Scripts: zudelloGetScript, zudelloListScripts, zudelloListGlobalIntegrations, zudelloListGlobalScriptsForIntegration
• Triggers: zudelloGetTrigger, zudelloListTriggers
• Logs: zudelloGetAutomationLogs, zudelloGetRunLogs, zudelloGetRunLogsContent, zudelloSearchRuns

Connections (5 tools)

• zudelloListConnections - List integration connections
• zudelloCheckConnectionStatus - Check connection status
• zudelloReconnect - Reconnect integration
• zudelloListAvailableIntegrations - List available integrations
• zudelloGetConnectionTemplate - Get connection template

Additional Categories

• Trigger & Sync Control (2 tools) - Enable/disable triggers, initiate syncs
• Bulk Operations (2 tools) - Bulk approve milestones, send reminders
• Approval Workflows (1 tool) - View approval configurations
• Users & Groups (2 tools) - Get users and user groups
• Admin Tools (13 tools) - Datasets, fields, quick actions
• Documents (12 tools) - Export templates, document types
• Organization Admin (9 tools) - Teams, users, groups management
• Notifications (3 tools) - Notification preferences
• Exception Reasons (6 tools) - Budget and contract exceptions
• Language (2 tools) - Custom terminology management
• Document Context (2 tools) - Budget and contract validation
• Inbox Management (8 tools) - Email inbox configuration
• Document Statuses (5 tools) - Status management
• History (1 tool) - Audit trail access

For a complete catalog of all 106 tools with detailed descriptions and parameters, see TOOL_CATALOG.md.

Tool Approval Metadata

Write tools (41 total) return approval metadata with risk levels:

High Risk (11 tools)

Operations that can significantly impact system behavior or data:

• Trigger/sync control, critical updates, org user creation

Medium Risk (24 tools)

Creation operations and bulk actions:

• Creating resources, bulk operations, org admin tasks

Low Risk (6 tools)

Safe operations with minimal impact:

• Reorder operations, notification preferences, exports

Approval metadata structure:

{
  requiresApproval: boolean,
  operation: string,
  riskLevel: "low" | "medium" | "high",
  reason: string,
  affectedResources?: string[],
  pendingAction?: any
}

Troubleshooting

"Server not found" or "Connection failed"

• Verify npx is available: npx --version
• Check your internet connection (npx may need to download the package)
• Try global installation: npm install -g @zudello/modelcontextprotocol

"Invalid credentials" or authentication errors

• Verify your ZUDELLO_TOKEN starts with "eyJ"
• Check ORGANIZATION and TEAM UUIDs are correct format
• Confirm CLUSTER_URL matches your Zudello instance region

Changes not taking effect

• Always restart Claude Desktop/Code after config changes
• Verify the config file is in the correct location
• Check for JSON syntax errors in your config file

Enable debug logging

Set LOG_LEVEL=debug in your environment variables to see detailed logs.

Documentation

• Tool Catalog - Complete reference of all 106 tools
• Development Guide - For contributors and local development
• Publishing Guide - For package maintainers

Development

See DEVELOPMENT.md for instructions on:

• Cloning and building from source
• Development workflow
• Running locally
• Contributing

Publishing

This package is automatically published to npm when code is pushed to the main branch via GitHub Actions.

For manual publishing instructions, see PUBLISHING.md.

License

MIT

Author

Zudello