node-zbooks-mcp-server

cosmonautaperuviano/node-zbooks-mcp-server

3.2

If you are the rightful owner of node-zbooks-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A robust Model Context Protocol (MCP) server for seamless integration with Zoho Books API, utilizing Node.js and TypeScript.

Tools

  1. Invoice Management

    Tools for listing, getting, and creating invoices.

  2. Contact Management

    Tools for listing, getting, and creating contacts.

  3. Item Management

    Tools for listing, getting, creating, and updating items.

  4. Sales Order Management

    Tools for listing and getting sales orders.

  5. Expense Management

    Tools for listing, getting, and creating expenses.

Zoho Books MCP Server - Node.js TypeScript Implementation

A powerful Model Context Protocol (MCP) server that provides seamless integration with Zoho Books API, built with Node.js and TypeScript. This implementation offers dual-endpoint support for both Claude Desktop and OpenAI API platforms.

šŸš€ Features

  • Dual-Endpoint Architecture: Supports both Claude Desktop (/sse) and OpenAI API (/mcp) endpoints
  • Type-Safe: Fully written in TypeScript with comprehensive type definitions
  • Modern Node.js: Built with ES modules and latest Node.js features
  • Robust Error Handling: Comprehensive error handling and logging
  • Health Monitoring: Built-in health checks and monitoring
  • Configurable: Flexible configuration via environment variables
  • Production Ready: Includes security, CORS, rate limiting, and more

šŸ“‹ Prerequisites

  • Node.js: 18.0.0 or higher
  • npm: 9.0.0 or higher
  • Zoho Books Account: With API access and OAuth credentials

šŸ› ļø Installation

1. Clone and Setup

# Clone the repository
git clone <repository-url>
cd node-zbooks-mcp

# Install dependencies
npm install

# Copy environment template
cp env.example .env

2. Configure Environment

Edit .env file with your Zoho Books credentials:

# Zoho API Configuration
ZOHO_CLIENT_ID=your_zoho_client_id_here
ZOHO_CLIENT_SECRET=your_zoho_client_secret_here
ZOHO_REFRESH_TOKEN=your_zoho_refresh_token_here
ZOHO_ORGANIZATION_ID=your_zoho_organization_id_here
ZOHO_REGION=com

# Server Configuration
NODE_ENV=development
PORT=8000
HOST=0.0.0.0

# Logging
LOG_LEVEL=info

šŸŽÆ Available Tools

The MCP server provides the following tools for Zoho Books integration:

Invoice Management

  • list_invoices - List invoices with filtering and pagination
  • get_invoice - Get specific invoice details
  • create_invoice - Create new invoices

Contact Management

  • list_contacts - List customers and vendors
  • get_contact - Get specific contact details
  • create_contact - Create new customers/vendors

Item Management

  • list_items - List products and services
  • get_item - Get specific item details
  • create_item - Create new items
  • update_item - Update existing items

Sales Order Management

  • list_sales_orders - List sales orders
  • get_sales_order - Get specific sales order details

Expense Management

  • list_expenses - List expenses with filtering
  • get_expense - Get specific expense details
  • create_expense - Create new expenses

Health Check

  • health_check - Test server and API connectivity

šŸš€ Usage

Development Mode

# Start in dual-endpoint mode (default)
npm run dev

# Start in Claude Desktop mode only
npm run start:claude

# Start in OpenAI API mode only
npm run start:openai

# Start with dual endpoints explicitly
npm run start:dual

Production Mode

# Build the project
npm run build

# Start production server
npm start

Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Health check
npm run health-check

šŸŒ API Endpoints

Health Check

GET /health

Root Information

GET /

Claude Desktop (SSE)

POST /sse/

OpenAI API (JSON-RPC)

POST /mcp/

šŸ”§ Configuration

Environment Variables

VariableDescriptionDefault
ZOHO_CLIENT_IDZoho OAuth Client IDRequired
ZOHO_CLIENT_SECRETZoho OAuth Client SecretRequired
ZOHO_REFRESH_TOKENZoho OAuth Refresh TokenRequired
ZOHO_ORGANIZATION_IDZoho Organization IDRequired
ZOHO_REGIONZoho region (com, eu, in, etc.)com
NODE_ENVEnvironment modedevelopment
PORTServer port8000
HOSTServer host0.0.0.0
LOG_LEVELLogging levelinfo
CORS_ORIGINSAllowed CORS origins*

Server Modes

The server supports multiple startup modes:

# Dual endpoints (Claude + OpenAI)
npm run dev

# Claude Desktop only (STDIO)
npm run dev -- --stdio
npm run dev -- --claude-only

# OpenAI API only (HTTP)
npm run dev -- --openai-only

# Dual HTTP endpoints
npm run dev -- --dual-endpoints

šŸ—ļø Project Structure

node-zbooks-mcp/
ā”œā”€ā”€ src/
ā”‚   ā”œā”€ā”€ config/          # Configuration management
ā”‚   ā”œā”€ā”€ tools/           # MCP tool implementations
ā”‚   ā”œā”€ā”€ types/           # TypeScript type definitions
ā”‚   ā”œā”€ā”€ utils/           # Utility functions
ā”‚   ā”œā”€ā”€ server/          # Server-specific modules
ā”‚   ā””ā”€ā”€ server.ts        # Main server entry point
ā”œā”€ā”€ scripts/             # Build and utility scripts
ā”œā”€ā”€ docs/                # Documentation
ā”œā”€ā”€ tests/               # Test files
ā”œā”€ā”€ dist/                # Compiled JavaScript (generated)
ā”œā”€ā”€ package.json         # Project configuration
ā”œā”€ā”€ tsconfig.json        # TypeScript configuration
ā””ā”€ā”€ README.md            # This file

šŸ” Security Features

  • Helmet: Security headers and protection
  • CORS: Configurable cross-origin resource sharing
  • Rate Limiting: Configurable request rate limiting
  • Input Validation: Zod-based schema validation
  • Error Handling: Secure error messages in production

šŸ“Š Monitoring & Logging

Logging

  • Winston: Structured logging with multiple transports
  • Log Levels: error, warn, info, debug
  • File Logging: Optional file output
  • JSON Format: Structured log format for analysis

Health Checks

  • API Connectivity: Tests Zoho Books API connection
  • Memory Usage: Monitors memory consumption
  • Uptime: Tracks server uptime
  • Custom Checks: Extensible health check system

šŸ› Troubleshooting

Common Issues

  1. Environment Variables Not Set

    Error: Missing required environment variables
    • Ensure all required variables are set in .env
    • Copy from env.example and fill in values

  2. Zoho API Authentication Failed

    Error: Failed to refresh access token
    • Verify Zoho OAuth credentials
    • Check refresh token is still valid
    • Ensure organization ID is correct

  3. Port Already in Use

    Error: EADDRINUSE: address already in use
    • Change PORT in .env file
    • Kill process using the port: lsof -ti:8000 | xargs kill

Debug Mode

Enable debug logging:

LOG_LEVEL=debug
DEBUG=zoho-mcp:*

šŸš€ Deployment

Docker (Recommended)

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
EXPOSE 8000
CMD ["node", "dist/server.js"]

PM2 Process Manager

{
  "name": "zoho-mcp-server",
  "script": "dist/server.js",
  "instances": "max",
  "exec_mode": "cluster",
  "env": {
    "NODE_ENV": "production",
    "PORT": 8000
  }
}

systemd Service

[Unit]
Description=Zoho Books MCP Server
After=network.target

[Service]
Type=simple
User=node
WorkingDirectory=/opt/zoho-mcp
ExecStart=/usr/bin/node dist/server.js
Restart=on-failure
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

šŸ¤ Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Run linting and tests
  6. Submit a pull request

Development Setup

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

šŸ“ License

MIT License - see LICENSE file for details.

šŸ”— Related Links

šŸ“ž Support

For issues and questions:

  1. Check the troubleshooting section
  2. Search existing issues
  3. Create a new issue

Built with ā¤ļø using Node.js, TypeScript, and the Model Context Protocol