PHPackages                             rajurayhan/laravel-quickbooks-mcp-server - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. rajurayhan/laravel-quickbooks-mcp-server

ActiveLibrary[API Development](/categories/api)

rajurayhan/laravel-quickbooks-mcp-server
========================================

QuickBooks Online MCP server for Laravel — expose QBO as AI-callable tools

1.0.0(3mo ago)922↓63.6%4MITPHPPHP ^8.2

Since Apr 2Pushed 3mo agoCompare

[ Source](https://github.com/rajurayhan/laravel-quickbooks-mcp-server)[ Packagist](https://packagist.org/packages/rajurayhan/laravel-quickbooks-mcp-server)[ RSS](/packages/rajurayhan-laravel-quickbooks-mcp-server/feed)WikiDiscussions main Synced 4w ago

READMEChangelog (1)Dependencies (4)Versions (2)Used By (0)

Laravel QuickBooks MCP
======================

[](#laravel-quickbooks-mcp)

A first-party PHP/Laravel Composer package that exposes **QuickBooks Online (QBO)** as a **Model Context Protocol (MCP) server**. AI clients — Claude, Cursor, n8n, and others — connect over HTTP and perform full CRUD operations on QBO entities using natural language.

This is the first PHP/Laravel QuickBooks MCP implementation in the ecosystem.

---

Features
--------

[](#features)

- **50 MCP tools** covering 11 QBO entities (customers, vendors, invoices, bills, estimates, purchases, employees, items, accounts, journal entries, and bill payments)
- **Remote HTTP transport** — not local stdio, so it works with any hosted AI client
- **Multi-tenant** — multiple QBO companies per Laravel installation
- **Name-to-ID resolution** — agents pass human-readable names; ID lookups happen automatically
- **Full OAuth 2.0 flow** — any SaaS user can connect their own QBO company
- **Production-ready** from day one (sandbox also supported)
- **Laravel-native auth** — works with Passport or Sanctum, no assumptions made

---

Requirements
------------

[](#requirements)

RequirementVersionPHP>= 8.2Laravel>= 11.x`laravel/mcp`^1.0`spinen/laravel-quickbooks-client`^4.0Your host application must also have:

- A `users` table with an `id` column (standard Laravel)
- The `HasQuickBooksToken` trait from `spinen/laravel-quickbooks-client` on the `User` model
- At least one configured auth guard that resolves `auth()->user()` from a Bearer token (Passport or Sanctum)

---

Installation
------------

[](#installation)

### 1. Install via Composer

[](#1-install-via-composer)

```
composer require rajurayhan/laravel-quickbooks-mcp-server
```

### 2. Publish package assets

[](#2-publish-package-assets)

```
# Publish config
php artisan vendor:publish --tag=quickbooks-mcp-config

# Publish migrations
php artisan vendor:publish --tag=quickbooks-mcp-migrations

# Publish routes stub
php artisan vendor:publish --tag=quickbooks-mcp-routes

# Or publish everything at once
php artisan vendor:publish --provider="Raju\QuickBooksMcp\QuickBooksMcpServiceProvider"
```

### 3. Run migrations

[](#3-run-migrations)

```
php artisan migrate
```

This creates one table: `quickbooks_connections`.

### 4. Configure your `.env`

[](#4-configure-your-env)

```
# Intuit app credentials (from developer.intuit.com)
QUICKBOOKS_CLIENT_ID=your_intuit_app_client_id
QUICKBOOKS_CLIENT_SECRET=your_intuit_app_client_secret
QUICKBOOKS_REDIRECT_URI=https://yourdomain.com/quickbooks/callback
QUICKBOOKS_SCOPE=com.intuit.quickbooks.accounting
QUICKBOOKS_DATA_SOURCE=production   # or: development (sandbox)

# MCP server settings
QBO_MCP_PATH=mcp/quickbooks
QBO_TOKEN_REFRESH_BUFFER=5
```

### 5. Register the published routes

[](#5-register-the-published-routes)

Open `routes/quickbooks-mcp.php` (published to your app's `routes/` folder) and register it in your application. Choose one of:

**Option A — in `app/Providers/AppServiceProvider.php`:**

```
public function boot(): void
{
    Route::middleware('web')
        ->group(base_path('routes/quickbooks-mcp.php'));
}
```

**Option B — at the bottom of `routes/web.php` or `routes/api.php`:**

```
require base_path('routes/quickbooks-mcp.php');
```

### 6. Set your auth guard

[](#6-set-your-auth-guard)

Inside `routes/quickbooks-mcp.php`, change `auth:api` to match your application's Bearer token guard:

```
// Change 'api' to 'sanctum' if your app uses Laravel Sanctum
Route::middleware([
    'api',
    'auth:api',   // ← change this line if needed
    ResolveQuickBooksRealm::class,
    RefreshQuickBooksToken::class,
])->group(function () {
    Mcp::server(QuickBooksServer::class)->at(config('quickbooks-mcp.path'));
});
```

### 7. Register your Intuit OAuth callback URI

[](#7-register-your-intuit-oauth-callback-uri)

In your [Intuit Developer app settings](https://developer.intuit.com), add this redirect URI:

```
https://yourdomain.com/quickbooks/callback

```

It must match the `/quickbooks/callback` route exactly.

### 8. Add `HasQuickBooksToken` to your User model

[](#8-add-hasquickbookstoken-to-your-user-model)

```
use Spinen\QuickBooks\HasQuickBooksToken;

class User extends Authenticatable
{
    use HasQuickBooksToken;
    // ...
}
```

---

OAuth Flow
----------

[](#oauth-flow)

Once installed, a SaaS user connects their QBO company through your application:

```
1. User visits GET /quickbooks/connect
   → Redirected to Intuit consent screen
   → Grants access to their QBO company
   → Redirected back to GET /quickbooks/callback

2. Callback handler:
   → Exchanges auth code for tokens (stored by spinen in quickbooks_tokens)
   → Package records connection in quickbooks_connections (realm_id + company_name)

3. User authenticates your app with their existing Bearer token (Passport or Sanctum)

4. AI client is configured with:
   MCP URL:  https://yourdomain.com/mcp/quickbooks
   Header:   Authorization: Bearer

5. Every MCP tool call thereafter:
   → Guard authenticates the Bearer token
   → ResolveQuickBooksRealm finds the user's active QBO connection
   → RefreshQuickBooksToken silently refreshes QBO tokens near expiry
   → Tool runs — zero extra params needed from the AI agent

```

### Connection management routes

[](#connection-management-routes)

MethodRouteDescription`GET``/quickbooks/connect`Redirect to Intuit OAuth consent screen`GET``/quickbooks/callback`Handle OAuth callback and store tokens`DELETE``/quickbooks/disconnect`Revoke QBO tokens and remove connection`GET``/quickbooks/connections`List active QBO connections for the user---

Configuration
-------------

[](#configuration)

`config/quickbooks-mcp.php`:

KeyDefaultDescription`path``mcp/quickbooks`URL path where the MCP server is exposed`multi_tenant``true`Resolve realm from authenticated user`search_limit``20`Default result limit for search tools`search_limit_max``100`Maximum result limit for search tools`environment``production`QBO environment (`production` or `development`)`redirect_uri``APP_URL/quickbooks/callback`OAuth redirect URI`token_refresh_buffer_minutes``5`Minutes before expiry to proactively refresh---

Available Tools
---------------

[](#available-tools)

### Account (3 tools)

[](#account-3-tools)

ToolDescription`create_account`Create a new account in the chart of accounts`search_accounts`Search accounts by name or type`update_account`Update an existing account### Bill (5 tools)

[](#bill-5-tools)

ToolDescription`create_bill`Create a new accounts payable bill`get_bill`Get a bill by ID`search_bills`Search bills by vendor, date range, or unpaid status`update_bill`Update an existing bill`delete_bill`Permanently delete a bill### Bill Payment (5 tools)

[](#bill-payment-5-tools)

ToolDescription`create_bill_payment`Pay one or more open bills`get_bill_payment`Get a bill payment by ID`search_bill_payments`Search bill payments by vendor or date range`update_bill_payment`Update an existing bill payment`delete_bill_payment`Permanently delete a bill payment### Customer (5 tools)

[](#customer-5-tools)

ToolDescription`create_customer`Create a new customer`get_customer`Get a customer by ID`search_customers`Search customers by name, email, or company`update_customer`Update an existing customer`delete_customer`Deactivate a customer (QBO soft-delete)### Employee (4 tools)

[](#employee-4-tools)

ToolDescription`create_employee`Create a new employee record`get_employee`Get an employee by ID`search_employees`Search employees by name or email`update_employee`Update an existing employee### Estimate (5 tools)

[](#estimate-5-tools)

ToolDescription`create_estimate`Create a new estimate / quote`get_estimate`Get an estimate by ID`search_estimates`Search estimates by customer, status, or date range`update_estimate`Update or change the status of an estimate`delete_estimate`Permanently delete an estimate### Invoice (4 tools)

[](#invoice-4-tools)

ToolDescription`create_invoice`Create a new invoice`read_invoice`Read a full invoice with all line items`search_invoices`Search invoices by customer, date range, or payment status`update_invoice`Update an existing invoice> Invoices cannot be permanently deleted in QBO.

### Item (4 tools)

[](#item-4-tools)

ToolDescription`create_item`Create a new product or service item`read_item`Read a full item record with pricing and account assignments`search_items`Search items by name or type`update_item`Update an existing item (set `active: false` to deactivate)> Items cannot be permanently deleted in QBO.

### Journal Entry (5 tools)

[](#journal-entry-5-tools)

ToolDescription`create_journal_entry`Create a journal entry (debits must equal credits)`get_journal_entry`Get a journal entry by ID`search_journal_entries`Search journal entries by date range or document number`update_journal_entry`Update an existing journal entry`delete_journal_entry`Permanently delete a journal entry### Purchase (5 tools)

[](#purchase-5-tools)

ToolDescription`create_purchase`Create a purchase / expense transaction`get_purchase`Get a purchase by ID`search_purchases`Search purchases by payment type or date range`update_purchase`Update an existing purchase`delete_purchase`Permanently delete a purchase### Vendor (5 tools)

[](#vendor-5-tools)

ToolDescription`create_vendor`Create a new vendor`get_vendor`Get a vendor by ID`search_vendors`Search vendors by name, email, or company`update_vendor`Update an existing vendor`delete_vendor`Deactivate a vendor (QBO soft-delete)---

Name Resolution
---------------

[](#name-resolution)

Tools that reference related entities (vendor, customer, account, item) accept either a **name** or a **numeric ID**. The package resolves names to IDs automatically before calling the QBO API.

```
# These are equivalent when calling create_bill:
vendor: "Office Depot"
vendor: "42"

```

If a name cannot be found, the tool returns a descriptive error with a suggestion to use the corresponding search tool first.

---

Delete Behaviour
----------------

[](#delete-behaviour)

QBO has two categories of delete:

BehaviourEntities**Soft-delete** — sets `Active = false`Customer, Vendor, Employee, Item, Account**Hard-delete** — permanently removedBill, BillPayment, Estimate, JournalEntry, Purchase**Cannot be deleted**Invoice, Item (use `update_item` with `active: false`)---

Multi-Tenant Architecture
-------------------------

[](#multi-tenant-architecture)

Each authenticated user has exactly one active QBO connection tracked in the `quickbooks_connections` table. The `ResolveQuickBooksRealm` middleware automatically scopes every tool call to the correct QBO company — no `realm_id` parameter is ever needed from the AI agent.

---

Package Architecture
--------------------

[](#package-architecture)

```
src/
├── QuickBooksMcpServiceProvider.php   — registers service, publishes assets
├── Server/QuickBooksServer.php        — MCP server, registers all 50 tools
├── Services/QuickBooksService.php     — QBO API wrapper, name resolvers
├── Concerns/ResolvesEntityNames.php   — trait for name-to-ID resolution
├── Http/
│   ├── Controllers/QuickBooksOAuthController.php
│   └── Middleware/
│       ├── ResolveQuickBooksRealm.php — scopes QBO service to user's company
│       └── RefreshQuickBooksToken.php — proactive token refresh
├── Models/QuickBooksConnection.php    — tracks user ↔ QBO company links
├── Exceptions/
│   ├── QuickBooksAuthException.php
│   └── QuickBooksToolException.php
└── Tools/                             — 50 tool classes across 11 entities
    ├── Account/, Bill/, BillPayment/, Customer/, Employee/
    ├── Estimate/, Invoice/, Item/, JournalEntry/
    ├── Purchase/, Vendor/

```

---

License
-------

[](#license)

MIT — see [LICENSE](LICENSE) for details.

---

Author
------

[](#author)

**Raju Rayhan** — [github.com/rajurayhan](https://github.com/rajurayhan)

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance82

Actively maintained with recent releases

Popularity16

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

90d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/6824950?v=4)[Raju Rayhan](/maintainers/rajurayhan)[@rajurayhan](https://github.com/rajurayhan)

---

Top Contributors

[![rajurayhan](https://avatars.githubusercontent.com/u/6824950?v=4)](https://github.com/rajurayhan "rajurayhan (7 commits)")

### Embed Badge

![Health badge](/badges/rajurayhan-laravel-quickbooks-mcp-server/health.svg)

```
[![Health](https://phpackages.com/badges/rajurayhan-laravel-quickbooks-mcp-server/health.svg)](https://phpackages.com/packages/rajurayhan-laravel-quickbooks-mcp-server)
```

###  Alternatives

[statamic/cms

The Statamic CMS Core Package

4.8k3.6M962](/packages/statamic-cms)[backpack/crud

Quickly build admin interfaces using Laravel, Bootstrap and JavaScript.

3.4k3.7M223](/packages/backpack-crud)[openai-php/laravel

OpenAI PHP for Laravel is a supercharged PHP API client that allows you to interact with the Open AI API

3.7k9.5M86](/packages/openai-php-laravel)[unopim/unopim

UnoPim Laravel PIM

10.5k2.4k](/packages/unopim-unopim)[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3741.3M46](/packages/tencentcloud-tencentcloud-sdk-php)[scriptdevelop/whatsapp-manager

Paquete para manejo de WhatsApp Business API en Laravel

783.8k](/packages/scriptdevelop-whatsapp-manager)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)