jasonsears/onebill-mcp-server

OneBill MCP Server

An MCP (Model Context Protocol) server that provides integration with OneBill's billing and invoice management system.

Features

Tools

• create_customer: Create new customers in OneBill
• create_invoice: Create invoices for customers
• send_invoice: Send invoices to customers via email
• record_payment: Record payments against invoices
• get_customer_balance: Get current balance for a customer
• get_overdue_invoices: Retrieve overdue invoices

Resources

• Customer List: List all customers in the system
• Recent Invoices: View recent invoices from the last 30 days
• Recent Payments: View recent payments from the last 30 days
• Customer Details: Get detailed information about specific customers
• Invoice Details: Get detailed information about specific invoices
• Customer Invoices: Get all invoices for a specific customer

Installation

1. Clone or download this repository
2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Configuration

The server requires the following environment variables:

• ONEBILL_API_KEY: Your OneBill API key (required)
• ONEBILL_TENANT_ID: Your OneBill tenant ID (required)
• ONEBILL_API_URL: OneBill API URL (optional, defaults to https://api.onebill.com/v1)

Usage

Running the Server Directly

ONEBILL_API_KEY=your_api_key ONEBILL_TENANT_ID=your_tenant_id npm start

Using with MCP Client

Add the server to your MCP client configuration:

{
  "mcpServers": {
    "onebill": {
      "command": "node",
      "args": ["/path/to/onebill-mcp-server/build/index.js"],
      "env": {
        "ONEBILL_API_KEY": "your_api_key",
        "ONEBILL_TENANT_ID": "your_tenant_id"
      }
    }
  }
}

API Integration

This server integrates with OneBill's REST API and provides the following functionality:

Customer Management

• Create new customers with name, email, phone, and address
• Retrieve customer details and balances
• List all customers

Invoice Management

• Create invoices with line items
• Send invoices to customers
• Track invoice status (draft, sent, paid, overdue, cancelled)
• Get invoice details and lists

Payment Processing

• Record payments against invoices
• Track payment methods and status
• View payment history

Reporting

• Get overdue invoices with optional filtering
• View recent activity summaries
• Access detailed customer and invoice reports

Development

Building

npm run build

Development Mode

npm run dev

Error Handling

The server includes comprehensive error handling for:

• Invalid API credentials
• Network connectivity issues
• Malformed requests
• OneBill API errors

All errors are properly logged and returned to the MCP client with appropriate error codes.

Security

• API keys are passed via environment variables
• All API requests use HTTPS
• Request validation ensures data integrity
• Tenant isolation via X-Tenant-ID header

License

MIT License