ScallyK/smallbiz-mcp

smallbiz-mcp-server

smallbiz-mcp is a TypeScript-based MCP server for small business operations, including calendar, CRM, sales, and marketing.

Note: Currently, smallbiz implements CRM tools from Square for invoice and customer management and calendar data from Google. Additional tools and resources for sales and marketing will be added soon.

Features

• Google Calendar Integration

  • Interface with Google Calendar data

• Square CRM

  • CRUD operations for Square customers
  • CRUD operations for Square invoices

Resources

Square

• Customers
  • List all: square://customer/listAll

Google

• List next 30 events: google://calendar/events/list

Tools

Core

• ping
  Basic ping tool. Always returns 'pong'.
• healthcheck
  Verifies server and backend dependencies (Redis, Postgres).

Square

• lookupSquareCustomerByEmail Search a Square customer by email. Parameters: email Returns: Customer details

• lookupSquareCustomerById Search a Square customer by customer ID. Parameters: customerId Returns: Customer details

• createSquareCustomer
  Create a customer in Square.
  Parameters: givenName, familyName, emailAddress, address, phoneNumber, referenceId, note
  Returns: Confirmation with customer ID

• updateSquareCustomer
  Update a Square customer.
  Parameters: customerId, address, birthday, company_name, email_address, family_name, given_name, nickname, note, phone_number, reference_id
  Returns: Confirmation with customer ID and timestamp

• deleteSquareCustomer
  Delete a Square customer.
  Parameters: customerId
  Returns: Confirmation with customer ID

• listInvoices Display all Square invoices by location ID. Parameters: locationId Returns: All invoices for a single location

• lookupSquareInvoiceById Search a Square invoice by invoice ID. Parameters: invoiceId Returns: Invoice details

• lookupSquareInvoiceByCustomer Search a Square invoice by customer ID and location ID. Parameters: customerId, locationId Returns: Invoice details

• createSquareInvoice
  Create an invoice in Square.
  Parameters: locationID, invoiceTitle, invoiceDescription, invoiceScheduledDate, customerId, invoiceDueDate, invoiceItems, serviceCharge, tax, discount
  Returns: Confirmation with invoice ID

• updateSquareInvoice
  Update a Square invoice.
  Parameters: acceptedPaymentMethods, paymentRequests, primaryRecipient, deliveryMethod, description, invoiceNumber, locationId, orderId, saleOrServiceDate, storePaymentMethodEnabled, title
  Returns: Confirmation with invoice ID

• deleteSquareInvoice
  Delete a Square invoice.
  Parameters: invoiceId
  Returns: Confirmation with invoice ID

Google

• lookupGoogleCalendarEventById Search for a Google Calendar event by event ID. Parameters: eventId Returns: Calendar event details

• createGoogleCalendarEvent
  Create a Google Calendar event.
  Parameters: eventTitle, eventDescription, eventStartDate, eventStartTime, eventEndDate, eventEndTime, attendees
  Returns: Confirmation, event details, and event link

• updateGoogleCalendarEvent
  Update a Google Calendar event.
  Parameters: eventId, eventTitle, eventDescription, eventStartDate, eventStartTime, eventEndDate, eventEndTime, attendees
  Returns: Confirmation, event details, and event link

• deleteGoogleCalendarEvent
  Delete a Google Calendar event.
  Parameters: eventId
  Returns: Confirmation

Prompts

• TBD

Development

Install dependencies:

npm install

Build the container:

docker compose up -d

Verify images:

docker compose logs postgres

Run Prisma migration:

npx prisma migrate dev --name init

Update Prisma client:

npx prisma generate

Build the server:

npm run build

Development with auto-rebuild:

npm run watch

Test with MCP Inspector:

npm run build
npx @modelcontextprotocol/inspector build/index.js

Installation

To use with Claude Desktop, add the server config:

• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "smallbiz-mcp-server": {
      "command": "/path/to/smallbiz-mcp-server/build/index.js"
    }
  }
}

Debugging

MCP servers communicate over stdio, which can make debugging challenging.
We recommend using the MCP Inspector:

npm run inspector

The Inspector provides a URL for browser-based debugging tools.

Run debug tools scripts:

node --loader ts-node/esm debug_tools/<script_here>

Other Notes

• For non-Windows machines, update the dev line in package.json to:

  "dev": "npx nodemon --watch src --ext ts --exec ts-node src/index.ts"
  

• Use npm install @modelcontextprotocol/sdk zod@3 (not zod@latest) to avoid compiler errors.

• Google Calendar integration:

  • Follow these steps
  • Create an external app
  • Add your email as a test user
  • If you subscribe to Google Workspace, you can set the app as internal.

• The MCP server may be unable to see your Google credentials. If so, add them to your .env file as an absolute path under GOOGLE_CREDENTIALS_PATH and GOOGLE_TOKEN_PATH.

Examples:

Example Screenshot