使用说明

Laravel QuickBooks MCP

一个第一方PHP/Lavel Composer包，它公开了 QuickBooks在线（QBO） 作为 模型上下文协议（MCP）服务器.AI客户端——Claude、Cursor、n8n和其他客户端——通过HTTP连接，并使用自然语言对QBO实体执行完整的CRUD操作。

这是生态系统中第一个PHP/Lavel QuickBooks MCP实现。

特性

50个MCP工具 涵盖11个QBO实体（客户、供应商、发票、账单、估算、采购、员工、项目、账户、日记账分录和账单付款）
远程HTTP传输 --不是本地stdio，因此它适用于任何托管的AI客户端
多用户 --每个Laravel安装都有多个QBO公司
名称到ID解析 --代理传递人类可读的名称；ID查找会自动进行
完整的OAuth 2.0流程 --任何SaaS用户都可以连接自己的QBO公司
生产就绪 从第一天开始（也支持沙盒）
Laravel原生身份验证 --与Passport或Sanctum合作，不作任何假设

需求

要求	版本
PHP	>=8.2
Laravel	>=11.x
`laravel/mcp`	^1.0
`spinen/laravel-quickbooks-client`	^4.0

您的主机应用程序还必须具有：

A. users 桌子与a id 列（标准Laravel）
这 HasQuickBooksToken 特征来自 spinen/laravel-quickbooks-client 在 User 模型
至少一个已配置的身份验证保护，用于解析 auth()->user() 来自不记名代币（护照或圣所）

安装

1.通过Composer安装

composer require rajurayhan/laravel-quickbooks-mcp-server

2.发布包资产

# 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.运行迁移

php artisan migrate

这将创建一个表： quickbooks_connections.

4.配置您的 `.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.登记已公布的路线

打开 routes/quickbooks-mcp.php （发布到您的应用程序 routes/ 文件夹）并将其注册到您的应用程序中。选择以下选项之一：

选项A-in app/Providers/AppServiceProvider.php:

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

选项B——位于底部 routes/web.php 或 routes/api.php:

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

6.设置您的身份验证保护

内部 routes/quickbooks-mcp.php，更改 auth:api 要匹配应用程序的Bearer令牌保护：

// 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.注册您的Intuit OAuth回调URI

在你的 Intuit Developer应用程序设置，添加此重定向URI：

https://yourdomain.com/quickbooks/callback

它必须与 /quickbooks/callback 路线准确。

8.添加 `HasQuickBooksToken` 到您的用户模型

use Spinen\QuickBooks\HasQuickBooksToken;

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

OAuth流

安装后，SaaS用户通过您的应用程序连接他们的QBO公司：

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 <bearer-token>

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

连接管理路由

方法	路线	描述
`GET`	`/quickbooks/connect`	重定向到Intuit OAuth同意屏幕
`GET`	`/quickbooks/callback`	处理OAuth回调并存储令牌
`DELETE`	`/quickbooks/disconnect`	撤销QBO令牌并删除连接
`GET`	`/quickbooks/connections`	列出用户的活动QBO连接

配置

config/quickbooks-mcp.php:

密钥	默认值	描述
`path`	`mcp/quickbooks`	暴露MCP服务器的URL路径
`multi_tenant`	`true`	从经过身份验证的用户解析领域
`search_limit`	`20`	搜索工具的默认结果限制
`search_limit_max`	`100`	搜索工具的最大结果限制
`environment`	`production`	QBO环境(`production` 或 `development`)
`redirect_uri`	`APP_URL/quickbooks/callback`	OAuth重定向URI
`token_refresh_buffer_minutes`	`5`	到期前几分钟主动刷新

可用工具

账户（3个工具）

工具	说明
`create_account`	在会计科目表中创建新帐户
`search_accounts`	按名称或类型搜索帐户
`update_account`	更新现有帐户

账单（5个工具）

工具	说明
`create_bill`	创建新的应付账款账单
`get_bill`	通过ID获取账单
`search_bills`	按供应商、日期范围或未付款状态搜索账单
`update_bill`	更新现有账单
`delete_bill`	永久删除账单

账单支付（5种工具）

工具	说明
`create_bill_payment`	支付一张或多张未结账单
`get_bill_payment`	通过ID获得账单付款
`search_bill_payments`	按供应商或日期范围搜索账单付款
`update_bill_payment`	更新现有账单付款
`delete_bill_payment`	永久删除账单付款

客户（5个工具）

工具	说明
`create_customer`	创建新客户
`get_customer`	通过ID获取客户
`search_customers`	按姓名、电子邮件或公司搜索客户
`update_customer`	更新现有客户
`delete_customer`	停用客户（QBO软删除）

员工（4个工具）

工具	说明
`create_employee`	创建新员工记录
`get_employee`	按ID获取员工
`search_employees`	按姓名或电子邮件搜索员工
`update_employee`	更新现有员工

估算（5个工具）

工具	说明
`create_estimate`	创建新的估算/报价
`get_estimate`	按ID获取估计值
`search_estimates`	按客户、状态或日期范围搜索估计值
`update_estimate`	更新或更改估算的状态
`delete_estimate`	永久删除估算

发票（4个工具）

工具	说明
`create_invoice`	创建新发票
`read_invoice`	阅读包含所有行项目的完整发票
`search_invoices`	按客户、日期范围或付款状态搜索发票
`update_invoice`	更新现有发票

QBO中不能永久删除发票。

项目（4个工具）

工具	说明
`create_item`	创建新产品或服务项
`read_item`	阅读包含定价和帐户分配的完整项目记录
`search_items`	按名称或类型搜索项目
`update_item`	更新现有项目（集 `active: false` 停用）

无法在QBO中永久删除项目。

日记账录入（5个工具）

工具	说明
`create_journal_entry`	创建日记账分录（借方必须等于贷方）
`get_journal_entry`	按ID获取日记条目
`search_journal_entries`	按日期范围或文档编号搜索日记账条目
`update_journal_entry`	更新现有日记账分录
`delete_journal_entry`	永久删除日记条目

购买（5个工具）

工具	说明
`create_purchase`	创建采购/支出交易记录
`get_purchase`	按ID购买
`search_purchases`	按付款类型或日期范围搜索购买
`update_purchase`	更新现有购买
`delete_purchase`	永久删除购买

供应商（5个工具）

工具	说明
`create_vendor`	创建新供应商
`get_vendor`	按ID获取供应商
`search_vendors`	按名称、电子邮件或公司搜索供应商
`update_vendor`	更新现有供应商
`delete_vendor`	停用供应商（QBO软删除）

名称解析

引用相关实体（供应商、客户、账户、项目）的工具接受名字或一个 数字ID.程序包在调用QBO API之前自动将名称解析为ID。

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

如果找不到名称，该工具将返回一个描述性错误，并建议先使用相应的搜索工具。

删除行为

QBO有两类删除：

行为	实体
软删除 --套装 `Active = false`	客户、供应商、员工、项目、账户
硬删除 --永久删除	账单、账单付款、估算、日记账录入、采购
无法删除	发票，项目（使用 `update_item` 随着 `active: false`)

多租户架构

每个经过身份验证的用户在 quickbooks_connections 桌子。这 ResolveQuickBooksRealm 中间件会自动将每个工具调用范围限定到正确的QBO公司——否 realm_id AI代理始终需要参数。

包装架构

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/

许可证

麻省理工学院——见许可证了解详情。

作者

拉朱·拉汉 — github/拉朱拉扬