node-zbooks-mcp-server

cosmonautaperuviano/node-zbooks-mcp-server

3.1

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
5
Resources
0
Prompts
0

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