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

$3

No installation required - use directly with npx:

``bash
npx @zudello/modelcontextprotocol
`

$3

Install globally to use without npx prefix:

`bash
npm install -g @zudello/modelcontextprotocol
`

Quick Start

$3

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

$3

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:
`json
{
"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

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:
`json
{
"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

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

$3

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

You should see a list of 106 available tools.

Configuration Details

$3

- 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)

$3

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)

$3


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

$3

- 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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

- 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:

$3

Operations that can significantly impact system behavior or data:
- Trigger/sync control, critical updates, org user creation

$3

Creation operations and bulk actions:
- Creating resources, bulk operations, org admin tasks

$3

Safe operations with minimal impact:
- Reorder operations, notification preferences, exports

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

Troubleshooting

$3


- 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

$3

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

$3

- 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

$3

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