quickbooks-mcp-server

Однофайловый MCP-сервер, который даёт Claude полный доступ на чтение и запись к QuickBooks Online, плюс инструменты сверки, которые находят то, чего человек, листающий регистр, не заметит.

$ qbo_health_check

  transport ...... stdio (Claude Desktop, Claude Code, claude.ai)
  api ............ QuickBooks Online v3
  tools .......... 22
  version ........ 2.0.0
  deploy ......... local, or HTTP on a Raspberry Pi behind Tailscale

Зачем это существует

Бухгалтерские вопросы почти никогда не сводятся к одному запросу. Вопрос «Мы заплатили этому поставщику дважды?» означает: выгрузить покупки, сгруппировать их по сумме и дате, свериться с банковской выпиской, а затем посмотреть, не был ли дубликат позже сторнирован. Это цикл, а циклы — это то, для чего и нужен агент.

Идея конструкции: дать модели небольшой набор компонуемых инструментов и позволить ей самой рассуждать, а не поставлять один огромный reconcile(), в который зашито моё суждение о том, что означает расхождение.

Именно поэтому в v2.0.0 22 инструмента, вместо 45 в v1.0.0. В первой версии был отдельный инструмент на каждый вопрос, который я когда-либо задавал. Оказалось, что большинство из них — это просто комбинация двух примитивов — поэтому примитивы остались, а составные инструменты были удалены. Карту миграции см. в CHANGELOG.md.

Related MCP server: penni-mcp

Инструменты

$ qbo --list-tools

  read
    qbo_company_info            qbo_get_preferences         qbo_health_check
    qbo_list_accounts           qbo_list_customers          qbo_get_customer
    qbo_list_bills              qbo_list_deposits           qbo_get_entity
    qbo_get_invoice             qbo_get_transaction         qbo_get_transfer
    qbo_get_journal_entry       qbo_get_report              qbo_account_register

  write
    qbo_create_invoice          qbo_create_payment          qbo_create_purchase
    qbo_delete_journal_entry    qbo_delete_purchase         qbo_delete_transfer
    qbo_batch_delete

  reconciliation
    qbo_detect_bank_feed_gaps       find dates where the feed silently stopped
    qbo_find_duplicate_transactions near-match scan across amount + date window
    qbo_duplicate_scan_by_account   the same, scoped to one account
    qbo_analyze_reconciliation      month-end variance with the arithmetic shown

Инструменты сверки — вот что стоит взятия на заметку. Пропуски в банковской выписке — это отказрежим, который никто не замечает — выгрузка останавливается на несколько дней, транзакции не поступают, а книги сходятся идеально на неполной картине. Никаких ошибок. Ты находишь только в марте, когда годовой баланс не сходится.

Установка

$ git clone https://github.com/rjpaganini/quickbooks-mcp-server
$ cd quickbooks-mcp-server
$ pip install -r requirements.txt
$ cp .env.example .env        # then fill in your QBO app credentials

Зарегистрируйте приложение на developer.intuit.com, чтобы получить client ID и client secret. Вам понадобятся:

  QB_REALM_ID          your company id
  QB_CLIENT_ID         from the Intuit developer app
  QB_CLIENT_SECRET     from the Intuit developer app
  QB_REFRESH_TOKEN     from the OAuth playground
  QB_ACCESS_TOKEN      refreshed automatically once seeded
  QB_SANDBOX           true while testing — set false deliberately

Затем укажите ваш MCP-клиент на него:

{
  "mcpServers": {
    "quickbooks": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Безопасность

Этот сервер может удалять данные в реальной системе бухгалтерского учёта. Это не гипотетика — qbo_batch_delete существует, потому что разгреcarь плохой импорт вручную — это мука.

Прочитайте SECURITY.md, прежде чем направлять его на реальную базу данных компании. Коротко: начните в песочнице, держите QB_SANDBOX=true, пока не посмотрите на его работу, и относитесь к инструментам записи и удаления так же, как к rm с жокерным символом.

$ pytest                       # unit tests, no network
$ pytest -m live               # smoke tests against a live sandbox company

Заметки

• Одно файл намеренно. server.py большой, но всё легко ищется grep-ом, и нет целого графа импортов, чтобы держать в голове.

• Также работает как HTTP-сервер на Raspberry Pi через deploy-to-pi.sh, именно так я обращаюсь к нему с claude.aiи через Tailscale на телефоне.

• Ни никто никаких учётных данных, данных компаний и финансовых записей в репозитории нет.

Лицензия

MIT.