Laravel QuickBooks MCP

Um pacote Composer PHP/Laravel de primeira parte que expõe o QuickBooks Online (QBO) como um servidor Model Context Protocol (MCP).

GitHub

Experimente este MCPPatrocinado

Documentação

Laravel QuickBooks MCP

Um pacote Composer PHP/Laravel de primeira parte que expõe o QuickBooks Online (QBO) como um servidor Model Context Protocol (MCP). Clientes de IA — Claude, Cursor, n8n e outros — conectam-se via HTTP e realizam operações completas de CRUD em entidades QBO usando linguagem natural.

Esta é a primeira implementação de MCP para PHP/Laravel QuickBooks no ecossistema.

Recursos

50 ferramentas MCP cobrindo 11 entidades QBO (clientes, fornecedores, faturas, contas a pagar, orçamentos, compras, funcionários, itens, contas, lançamentos contábeis e pagamentos de contas)
Transporte HTTP remoto — não é stdio local, então funciona com qualquer cliente de IA hospedado
Multi-tenant — múltiplas empresas QBO por instalação Laravel
Resolução nome-para-ID — agentes passam nomes legíveis; a busca de IDs acontece automaticamente
Fluxo OAuth 2.0 completo — qualquer usuário SaaS pode conectar sua própria empresa QBO
Pronto para produção desde o primeiro dia (sandbox também é suportado)
Autenticação nativa Laravel — funciona com Passport ou Sanctum, sem suposições

Requisitos

Requisito	Versão
PHP	>= 8.2
Laravel	>= 11.x
`laravel/mcp`	^1.0
`spinen/laravel-quickbooks-client`	^4.0

Seu aplicativo host também deve ter:

Uma tabela users com uma coluna id (padrão Laravel)
O trait HasQuickBooksToken do spinen/laravel-quickbooks-client no modelo User
Pelo menos um guard de autenticação configurado que resolva auth()->user() a partir de um token Bearer (Passport ou Sanctum)

Instalação

1. Instalar via Composer

composer require rajurayhan/laravel-quickbooks-mcp-server

2. Publicar os assets do pacote

# 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. Executar as migrações

php artisan migrate

Isso cria uma tabela: quickbooks_connections.

4. Configurar seu `.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. Registrar as rotas publicadas

Abra routes/quickbooks-mcp.php (publicado na pasta routes/ do seu aplicativo) e registre-o no seu aplicativo. Escolha uma das opções:

Opção A — em app/Providers/AppServiceProvider.php:

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

Opção B — no final de routes/web.php ou routes/api.php:

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

6. Definir seu guard de autenticação

Dentro de routes/quickbooks-mcp.php, altere auth:api para corresponder ao guard de token Bearer do seu aplicativo:

// 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. Registrar seu URI de callback OAuth da Intuit

Nas configurações do aplicativo Intuit Developer, adicione este URI de redirecionamento:

https://yourdomain.com/quickbooks/callback

Ele deve corresponder exatamente à rota /quickbooks/callback.

8. Adicionar `HasQuickBooksToken` ao seu modelo User

use Spinen\QuickBooks\HasQuickBooksToken;

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

Fluxo OAuth

Uma vez instalado, um usuário SaaS conecta sua empresa QBO através do seu aplicativo:

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

Rotas de gerenciamento de conexão

Método	Rota	Descrição
`GET`	`/quickbooks/connect`	Redirecionar para a tela de consentimento OAuth da Intuit
`GET`	`/quickbooks/callback`	Lidar com o callback OAuth e armazenar tokens
`DELETE`	`/quickbooks/disconnect`	Revogar tokens QBO e remover conexão
`GET`	`/quickbooks/connections`	Listar conexões QBO ativas do usuário

Configuração

config/quickbooks-mcp.php:

Chave	Padrão	Descrição
`path`	`mcp/quickbooks`	Caminho da URL onde o servidor MCP é exposto
`multi_tenant`	`true`	Resolver realm a partir do usuário autenticado
`search_limit`	`20`	Limite padrão de resultados para ferramentas de busca
`search_limit_max`	`100`	Limite máximo de resultados para ferramentas de busca
`environment`	`production`	Ambiente QBO (`production` ou `development`)
`redirect_uri`	`APP_URL/quickbooks/callback`	URI de redirecionamento OAuth
`token_refresh_buffer_minutes`	`5`	Minutos antes da expiração para renovar proativamente

Ferramentas Disponíveis

Conta (3 ferramentas)

Ferramenta	Descrição
`create_account`	Criar uma nova conta no plano de contas
`search_accounts`	Buscar contas por nome ou tipo
`update_account`	Atualizar uma conta existente

Conta a Pagar (5 ferramentas)

Ferramenta	Descrição
`create_bill`	Criar uma nova conta a pagar
`get_bill`	Obter uma conta a pagar por ID
`search_bills`	Buscar contas a pagar por fornecedor, intervalo de datas ou status de não pago
`update_bill`	Atualizar uma conta a pagar existente
`delete_bill`	Excluir permanentemente uma conta a pagar

Pagamento de Conta (5 ferramentas)

Ferramenta	Descrição
`create_bill_payment`	Pagar uma ou mais contas a pagar em aberto
`get_bill_payment`	Obter um pagamento de conta por ID
`search_bill_payments`	Buscar pagamentos de contas por fornecedor ou intervalo de datas
`update_bill_payment`	Atualizar um pagamento de conta existente
`delete_bill_payment`	Excluir permanentemente um pagamento de conta

Cliente (5 ferramentas)

Ferramenta	Descrição
`create_customer`	Criar um novo cliente
`get_customer`	Obter um cliente por ID
`search_customers`	Buscar clientes por nome, e-mail ou empresa
`update_customer`	Atualizar um cliente existente
`delete_customer`	Desativar um cliente (exclusão suave do QBO)

Funcionário (4 ferramentas)

Ferramenta	Descrição
`create_employee`	Criar um novo registro de funcionário
`get_employee`	Obter um funcionário por ID
`search_employees`	Buscar funcionários por nome ou e-mail
`update_employee`	Atualizar um funcionário existente

Orçamento (5 ferramentas)

Ferramenta	Descrição
`create_estimate`	Criar um novo orçamento / cotação
`get_estimate`	Obter um orçamento por ID
`search_estimates`	Buscar orçamentos por cliente, status ou intervalo de datas
`update_estimate`	Atualizar ou alterar o status de um orçamento
`delete_estimate`	Excluir permanentemente um orçamento

Fatura (4 ferramentas)

Ferramenta	Descrição
`create_invoice`	Criar uma nova fatura
`read_invoice`	Ler uma fatura completa com todos os itens de linha
`search_invoices`	Buscar faturas por cliente, intervalo de datas ou status de pagamento
`update_invoice`	Atualizar uma fatura existente

Faturas não podem ser excluídas permanentemente no QBO.

Item (4 ferramentas)

Ferramenta	Descrição
`create_item`	Criar um novo item de produto ou serviço
`read_item`	Ler um registro completo de item com preços e atribuições de conta
`search_items`	Buscar itens por nome ou tipo
`update_item`	Atualizar um item existente (defina `active: false` para desativar)

Itens não podem ser excluídos permanentemente no QBO.

Lançamento Contábil (5 ferramentas)

Ferramenta	Descrição
`create_journal_entry`	Criar um lançamento contábil (débitos devem ser iguais a créditos)
`get_journal_entry`	Obter um lançamento contábil por ID
`search_journal_entries`	Buscar lançamentos contábeis por intervalo de datas ou número de documento
`update_journal_entry`	Atualizar um lançamento contábil existente
`delete_journal_entry`	Excluir permanentemente um lançamento contábil

Compra (5 ferramentas)

Ferramenta	Descrição
`create_purchase`	Criar uma transação de compra / despesa
`get_purchase`	Obter uma compra por ID
`search_purchases`	Buscar compras por tipo de pagamento ou intervalo de datas
`update_purchase`	Atualizar uma compra existente
`delete_purchase`	Excluir permanentemente uma compra

Fornecedor (5 ferramentas)

Ferramenta	Descrição
`create_vendor`	Criar um novo fornecedor
`get_vendor`	Obter um fornecedor por ID
`search_vendors`	Buscar fornecedores por nome, e-mail ou empresa
`update_vendor`	Atualizar um fornecedor existente
`delete_vendor`	Desativar um fornecedor (exclusão suave do QBO)

Resolução de Nomes

Ferramentas que referenciam entidades relacionadas (fornecedor, cliente, conta, item) aceitam tanto um nome quanto um ID numérico. O pacote resolve nomes para IDs automaticamente antes de chamar a API QBO.

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

Se um nome não puder ser encontrado, a ferramenta retorna um erro descritivo com uma sugestão para usar a ferramenta de busca correspondente primeiro.

Comportamento de Exclusão

O QBO tem duas categorias de exclusão:

Comportamento	Entidades
Exclusão suave — define `Active = false`	Cliente, Fornecedor, Funcionário, Item, Conta
Exclusão definitiva — removido permanentemente	Conta a Pagar, Pagamento de Conta, Orçamento, Lançamento Contábil, Compra
Não pode ser excluído	Fatura, Item (use `update_item` com `active: false`)

Arquitetura Multi-Tenant

Cada usuário autenticado tem exatamente uma conexão QBO ativa rastreada na tabela quickbooks_connections. O middleware ResolveQuickBooksRealm automaticamente limita cada chamada de ferramenta à empresa QBO correta — nenhum parâmetro realm_id é necessário do agente de IA.

Arquitetura do Pacote

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/

Licença

MIT — veja LICENSE para detalhes.

Autor

Raju Rayhan — github.com/rajurayhan

Laravel QuickBooks MCP

Documentação

Laravel QuickBooks MCP

Recursos

Requisitos

Instalação

1. Instalar via Composer

2. Publicar os assets do pacote

3. Executar as migrações

4. Configurar seu .env

5. Registrar as rotas publicadas

6. Definir seu guard de autenticação

7. Registrar seu URI de callback OAuth da Intuit

8. Adicionar HasQuickBooksToken ao seu modelo User

Fluxo OAuth

Rotas de gerenciamento de conexão

Configuração

Ferramentas Disponíveis

Conta (3 ferramentas)

Conta a Pagar (5 ferramentas)

Pagamento de Conta (5 ferramentas)

Cliente (5 ferramentas)

Funcionário (4 ferramentas)

Orçamento (5 ferramentas)

Fatura (4 ferramentas)

Item (4 ferramentas)

Lançamento Contábil (5 ferramentas)

Compra (5 ferramentas)

Fornecedor (5 ferramentas)

Resolução de Nomes

Comportamento de Exclusão

Arquitetura Multi-Tenant

Arquitetura do Pacote

Licença

Autor

4. Configurar seu `.env`

8. Adicionar `HasQuickBooksToken` ao seu modelo User