Laravel Quickbooks MCP Server

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合作，不作任何假设

______________________________________________________________________

需求

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

• 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 

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

连接管理路由

______________________________________________________________________

配置

config/quickbooks-mcp.php:

______________________________________________________________________

可用工具

账户（3个工具）

账单（5个工具）

账单支付（5种工具）

客户（5个工具）

员工（4个工具）

估算（5个工具）

发票（4个工具）

QBO中不能永久删除发票。

项目（4个工具）

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

日记账录入（5个工具）

购买（5个工具）

供应商（5个工具）

______________________________________________________________________

名称解析

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

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

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

______________________________________________________________________

删除行为

QBO有两类删除：

______________________________________________________________________

多租户架构

每个经过身份验证的用户在 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/

______________________________________________________________________

许可证

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

______________________________________________________________________

作者

拉朱·拉汉 —