hostbill-mcp-server

shadm-gh/hostbill-mcp-server

3.2

If you are the rightful owner of hostbill-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 dayong@mcphub.com.

HostBill MCP Server provides standardized access to HostBill's API, enabling AI agents to manage various business operations.

Tools
15
Resources
0
Prompts
0

HostBill MCP Server

A production-ready Model Context Protocol (MCP) server that provides standardized access to HostBill's comprehensive API, enabling AI agents to manage clients, billing, support tickets, domains, and hosting services.

Overview

This MCP server exposes HostBill's 70+ API methods through 15 well-organized tools, following MCP best practices to prevent tool budget overwhelm while maintaining full functionality. The server handles authentication, error translation, logging, and provides intelligent grouping of related operations.

Features

  • 15 Organized Tools - Logical grouping of 70+ HostBill API methods by business domain
  • Client Management - Search, retrieve, create, update, and delete client accounts
  • Service Accounts - Manage hosting services, suspensions, and terminations
  • Billing & Invoices - Create invoices, process payments, search billing records
  • Support Tickets - Full ticket lifecycle management with replies and status updates
  • Domain Management - Check availability, register, and manage domains
  • Order Processing - Browse products and manage order lifecycle
  • Comprehensive Error Handling - Structured errors with proper categorization
  • Logging - Winston-based structured logging with correlation IDs
  • Input Validation - Zod schemas for all parameters
  • Connection Pooling - Axios with automatic retry logic

Installation

  1. Clone or download this repository

  2. Install dependencies

npm install
  1. Configure environment variables

Copy .env.example to .env and fill in your HostBill credentials:

cp .env.example .env

Edit .env:

HOSTBILL_URL=https://your-hostbill-instance.com
HOSTBILL_API_ID=your_api_id
HOSTBILL_API_KEY=your_api_key
NODE_ENV=development
LOG_LEVEL=info
  1. Build the project
npm run build

Usage

Running the Server

npm start

Development Mode with Watch

npm run watch

Then in another terminal:

npm start

Testing with MCP Inspector

npm run inspect

Available Tools

Client Management (3 tools)

search-clients

Search and list client accounts with pagination.

  • Parameters: query, page, perPage
  • Returns: List of clients with pagination info
get-client-profile

Retrieve complete client information including orders, invoices, domains, and tickets.

  • Parameters: clientId
  • Returns: Comprehensive client profile with related data
manage-client

Create, update, or delete client accounts.

  • Parameters: action (create/update/delete), client details
  • Actions:
    • create: Add new client
    • update: Modify client details
    • delete: Remove client

Service Accounts (2 tools)

list-services

List and filter service accounts with pagination.

  • Parameters: status, page, perPage
  • Returns: List of service accounts
manage-service

Create, modify, suspend, unsuspend, or terminate services.

  • Parameters: action (create/update/suspend/unsuspend/terminate)
  • Actions:
    • create: Provision new service
    • update: Modify service details
    • suspend: Suspend service
    • unsuspend: Reactivate service
    • terminate: Terminate service

Billing & Invoices (3 tools)

search-invoices

List and filter invoices with pagination.

  • Parameters: status, page, perPage
  • Returns: List of invoices
create-invoice

Create new invoice with line items.

  • Parameters: clientId, items, dueDate
  • Returns: Invoice ID and creation status
process-payment

Apply payments or charge credit cards.

  • Parameters: action (record/charge), invoiceId, amount
  • Actions:
    • record: Record manual payment
    • charge: Charge credit card on file

Support Tickets (3 tools)

search-tickets

List and filter support tickets.

  • Parameters: status, priority, page, perPage
  • Returns: List of tickets
get-ticket-thread

Retrieve full ticket with all replies.

  • Parameters: ticketId
  • Returns: Ticket details with full conversation thread
manage-ticket

Create tickets, add replies, update status/priority.

  • Parameters: action (create/reply/update-status/update-priority)
  • Actions:
    • create: Open new ticket
    • reply: Add reply to ticket
    • update-status: Change ticket status
    • update-priority: Change ticket priority

Domain Management (2 tools)

check-domain-availability

Check if a domain is available for registration.

  • Parameters: domain
  • Returns: Availability status
manage-domain

Register, edit, or get domain details.

  • Parameters: action (register/edit/get), domain details
  • Actions:
    • register: Register new domain
    • edit: Update domain details
    • get: Retrieve domain information

Orders & Products (2 tools)

browse-products

List available products with pricing.

  • Parameters: page, perPage
  • Returns: Product catalog with pricing tiers
manage-order

Create and manage orders.

  • Parameters: action (create/activate/cancel), order details
  • Actions:
    • create: Create new order
    • activate: Activate pending order
    • cancel: Cancel order

Architecture

hostbill-mcp-server/
├── src/
│   ├── index.ts              # Server initialization and tool registration
│   ├── tools/                # MCP tool implementations
│   │   ├── clients.ts        # Client management tools
│   │   ├── accounts.ts       # Service account tools
│   │   ├── invoices.ts       # Billing and invoice tools
│   │   ├── tickets.ts        # Support ticket tools
│   │   ├── domains.ts        # Domain management tools
│   │   └── orders.ts         # Order processing tools
│   ├── services/
│   │   └── hostbill.ts       # HostBill API client wrapper
│   ├── config/
│   │   └── auth.ts           # Configuration management
│   └── utils/
│       ├── errors.ts         # Error handling utilities
│       ├── logger.ts         # Structured logging
│       └── validation.ts     # Input validation schemas
├── build/                    # Compiled JavaScript
├── .env                      # Environment configuration
├── package.json
└── tsconfig.json

Security

  • Environment Variables: Never hardcode credentials
  • Input Validation: Zod schemas prevent injection attacks
  • Error Handling: Structured errors without sensitive data leakage
  • IP Whitelisting: Configure in HostBill admin panel
  • API Permissions: Use function-level access control in HostBill

Error Handling

The server uses structured error categories:

  • AUTHENTICATION_ERROR - Invalid API credentials
  • PERMISSION_ERROR - API key lacks required permissions
  • VALIDATION_ERROR - Invalid parameters
  • RESOURCE_NOT_FOUND - Entity doesn't exist
  • API_ERROR - HostBill API error
  • NETWORK_ERROR - Connection failure
  • RATE_LIMIT - Too many requests

All errors are logged with correlation IDs for debugging.

Logging

Logs are written to:

  • error.log - Error level logs only
  • combined.log - All logs
  • Console - Formatted output for development

Log entries include:

  • Correlation IDs for request tracing
  • Tool invocation details
  • API call latency metrics
  • Error context and stack traces

API Integration

The server uses HostBill's Admin API:

  • Endpoint: {HOSTBILL_URL}/admin/api.php
  • Method: HTTP POST
  • Authentication: API ID + API Key
  • Response Format: JSON with success boolean

Pagination

Most list operations support pagination:

  • Default: 25 records per page
  • Maximum: 100 records per page
  • Response includes hasMore indicator

Docker Deployment

Building the Docker Image

# Build the image
docker build -t hostbill-mcp-server .

# Or use docker-compose
docker-compose build

Running with Docker

Option 1: Using docker run

docker run -d \
  --name hostbill-mcp-server \
  -e HOSTBILL_URL=https://your-hostbill-instance.com \
  -e HOSTBILL_API_ID=your_api_id \
  -e HOSTBILL_API_KEY=your_api_key \
  -e NODE_ENV=production \
  -e LOG_LEVEL=info \
  -v $(pwd)/logs:/app/logs \
  hostbill-mcp-server

Option 2: Using docker-compose

  1. Create a .env file with your credentials:
HOSTBILL_URL=https://your-hostbill-instance.com
HOSTBILL_API_ID=your_api_id
HOSTBILL_API_KEY=your_api_key
NODE_ENV=production
LOG_LEVEL=info
  1. Start the container:
docker-compose up -d
  1. View logs:
docker-compose logs -f
  1. Stop the container:
docker-compose down

Docker Image Features

  • Multi-stage build - Optimized image size
  • Non-root user - Runs as unprivileged user for security
  • Health checks - Automatic container health monitoring
  • Resource limits - CPU and memory constraints
  • Persistent logs - Volume mounting for log persistence
  • Alpine Linux - Minimal base image (~150MB total)

Docker Commands

# Check container status
docker-compose ps

# View logs
docker-compose logs -f hostbill-mcp-server

# Restart container
docker-compose restart

# Rebuild after code changes
docker-compose up -d --build

# Execute commands in container
docker-compose exec hostbill-mcp-server sh

# Remove container and volumes
docker-compose down -v

Production Docker Deployment

For production environments:

  1. Use secrets management:
# Use Docker secrets or Kubernetes secrets
docker secret create hostbill_api_key /path/to/api_key.txt
  1. Configure monitoring:
# Add to docker-compose.yml
logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"
  1. Use orchestration (Kubernetes example):
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hostbill-mcp-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: hostbill-mcp-server
  template:
    metadata:
      labels:
        app: hostbill-mcp-server
    spec:
      containers:
      - name: hostbill-mcp-server
        image: hostbill-mcp-server:latest
        env:
        - name: HOSTBILL_URL
          valueFrom:
            secretKeyRef:
              name: hostbill-secrets
              key: url
        resources:
          limits:
            cpu: "1"
            memory: "512Mi"
          requests:
            cpu: "500m"
            memory: "256Mi"

Development

TypeScript Compilation

npm run build

Watch Mode

npm run watch

Logging Levels

Set LOG_LEVEL in .env:

  • error - Errors only
  • warn - Warnings and errors
  • info - General information (default)
  • debug - Detailed debugging

Production Deployment

For production use, consider:

  1. Environment: Set NODE_ENV=production
  2. HTTPS Transport: Implement Streamable HTTP with OAuth 2.1
  3. Secret Management: Use secure secret storage (AWS Secrets Manager, etc.)
  4. Monitoring: Configure monitoring and alerting
  5. Rate Limiting: Implement client-side rate limiting
  6. Docker: Use the provided Dockerfile and docker-compose.yml

Troubleshooting

Connection Issues

  • Verify HOSTBILL_URL is correct and accessible
  • Check API credentials are valid
  • Ensure IP is whitelisted in HostBill
  • Verify API key has required function permissions

Authentication Errors

  • Regenerate API credentials in HostBill admin panel
  • Check IP whitelisting configuration
  • Verify API key has access to required functions

Tool Failures

  • Check logs in error.log and combined.log
  • Look for correlation IDs in error messages
  • Verify input parameters match schema requirements

Contributing

This server follows MCP best practices and HostBill API conventions. When adding new tools:

  1. Add validation schemas in utils/validation.ts
  2. Create tool handlers following existing patterns
  3. Register tools in index.ts
  4. Add comprehensive error handling
  5. Include logging for debugging
  6. Update README documentation

License

MIT

Support

For HostBill API documentation, visit your HostBill instance at: https://your-hostbill-instance.com/admin/api.php

For MCP documentation:

Acknowledgments

Built with: