MCP server exposing 106 Zudello ERP automation tools for Claude Desktop and other MCP-compatible clients
npm install @zudello/modelcontextprotocolModel Context Protocol (MCP) server exposing 106 Zudello ERP automation tools for use with Claude Desktop, Claude Code CLI, and other MCP-compatible clients.
- 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
No installation required - use directly with npx:
``bash`
npx @zudello/modelcontextprotocol
Install globally to use without npx prefix:
`bash`
npm install -g @zudello/modelcontextprotocol
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
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"
}
}
}
}
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"
}
}
}
}
Restart Claude Desktop or Claude Code CLI to load the new configuration.
Ask Claude: "What Zudello MCP tools are available?"
You should see a list of 106 available tools.
- 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)
The MCP server uses two different API endpoints:
1. Team-Level API (ZUDELLO_CLUSTER_URL): Used for most operations (97 tools)api.1.eur1.zudello.io
- Region-specific endpoints for team data and operations
- Examples: , api.au.3.zudello.io, api.us.1.zudello.io
2. Organization-Level API (AUTHENTICATION_API_BASE): Used for org admin operations (9 tools)api.1.global.zudello.io
- Default:
- Global endpoint for cross-team operations (teams, users, groups)
- 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 accessFor 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, exportsApproval 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.
MIT
Zudello