QuickBooks Online을 위한 Model Context Protocol 서버입니다. 5분 안에 Claude를 귀하의 장부(고객, 공급업체, 송장, 청구서 및 계정과목표)에 읽기 전용으로 연결하세요.
약 700만 개의 기업이 QuickBooks Online(QBO)을 사용하여 장부를 관리합니다. Intuit는 유능한 REST API를 제공하지만 공식 MCP 서버는 없기 때문에, Claude(또는 MCP를 지원하는 AI 어시스턴트)가 장부를 확인하기를 원하는 모든 팀은 매번 OAuth와 페이지네이션 처리를 처음부터 직접 구현해야 합니다.
만약 Claude를 사용하여 일상적인 재무 업무(미수금 추적, 매입채무 확인, 이사회 보고 준비 등)를 처리한다면, 이러한 격차는 "3월 말에 Acme가 우리에게 얼마를 빚지고 있었지?"라는 질문이 즉시 작동하는 것과, 커스텀 통합이 필요한 것 사이의 차이를 만듭니다.
qbo-mcp는 그 격차를 해소합니다. 이 서버는 8개의 읽기 전용 QBO 엔드포인트를 모든 MCP 클라이언트에 노출하는 작고 잘 테스트된 MIT 라이선스 MCP 서버입니다. 실제 자금 흐름에 대해 수년간 QBO 자동화를 운영하며 얻은 경험을 바탕으로, 프로덕션 환경에서 발생하는 모든 문제(토큰 갱신, 429 제한, 페이지 중간 만료, 쿼리 문자열 이스케이프 등)를 client.py에서 처리하므로 직접 고생할 필요가 없습니다.
Related MCP server: qbo-mcp
이 서버를 Claude Code, Claude Desktop 또는 모든 MCP 호스트에 연결한 후 다음과 같이 질문해 보세요:
"'Acme'와 일치하는 모든 고객을 찾아 잔액을 보여줘."
"지금 WidgetCo에 우리가 얼마를 빚지고 있지? 미결제 청구서 목록을 보여줘."
"이번 달에 생성된 모든 미납 송장을 가져와서 고객별로 그룹화해줘."
"계정과목표는 어떻게 구성되어 있지? 모든 은행 및 기타 유동 자산 계정과 현재 잔액을 나열해줘."
"지난주 청구서 발행량과 지난달 같은 주를 비교해줘."
Claude가 귀하의 장부를 직접 읽습니다. 복사-붙여넣기, 스프레드시트, 커스텀 파이프라인이 필요 없습니다.
도구 | 기능 |
| 표시 이름으로 고객 찾기 (부분 일치, 대소문자 구분 안 함). |
| ID로 고객 한 명 가져오기. |
| 표시 이름으로 공급업체 찾기. |
| ID로 공급업체 한 명 가져오기. |
| 날짜 범위 내 송장 나열 (선택적으로 미결제/결제 완료 필터링). |
| 라인 항목을 포함하여 ID로 송장 한 개 가져오기. |
| 날짜 범위 내 청구서 나열 (선택적으로 미결제/결제 완료 필터링). |
| 잔액이 포함된 활성 계정과목표 반환. |
쓰기 엔드포인트(송장 생성, 청구서 생성, 분개장 입력)는 의도적으로 v0.1에 포함되지 않았습니다. 읽기 전용 기능이 안정화된 후 v0.2에서 계획될 예정입니다. 읽기 기능이 충분히 검증될 때까지 장부에 직접 쓰기 작업을 수행하는 도구는 배포하지 않을 것입니다.
pip install qbo-mcpv0.1은 이 저장소에서 제공됩니다. PyPI 배포는 대기 중입니다. 현재는
pip install git+https://github.com/alveyautomation/qbo-mcp를 사용하거나 로컬에서 클론 후pip install -e .를 실행하여 설치하세요.
QBO는 갱신 토큰(refresh token)이 순환되는 OAuth 2.0을 사용합니다. 이 과정은 한 번만 수행하면 되며, 그 후 qbo-mcp는 (최소 100일에 한 번 실행되는 한) 영구적으로 인증 상태를 유지합니다. 총 소요 시간: 약 60초.
https://developer.intuit.com/에서 앱을 생성합니다. Accounting 범위를 선택하세요. client_id와 client_secret을 복사합니다.
https://developer.intuit.com/app/developer/playground에서 OAuth Playground를 방문합니다. 앱을 선택하고 환경(Sandbox 또는 Production)을 선택한 후 Get Authorization Code를 클릭합니다. 연결하려는 QuickBooks 회사 계정으로 로그인합니다.
코드를 토큰으로 교환합니다(Playground가 자동으로 수행합니다). 다음을 복사하세요:
refresh_token (긴 문자열, 100일 동안 비활성 상태 유지)
realmId (숫자, QBO 회사를 식별)
.env 파일에 저장합니다:
QBO_CLIENT_ID=ABxxxxxxxxxxxxxx
QBO_CLIENT_SECRET=xxxxxxxxxxxxxxxx
QBO_REFRESH_TOKEN=ABxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
QBO_REALM_ID=1234567890123456
QBO_ENVIRONMENT=production # or "sandbox"이것으로 끝입니다. 첫 번째 도구 호출 시 갱신 토큰이 액세스 토큰으로 교환되며, 이후 호출은 액세스 토큰이 만료될 때까지(~55분) 캐시된 토큰을 재사용하고, 만료 시 클라이언트가 자동으로 갱신합니다.
갱신 토큰 순환: Intuit는 갱신할 때마다 새로운 갱신 토큰을 발행하고 이전 토큰을 즉시 무효화합니다. 배포 환경이 단일 장기 실행 프로세스라면 이 과정은 보이지 않게 처리됩니다. 배포가 자주 재시작되는 환경(컨테이너, 서버리스)이라면 순환된 토큰을 영구 저장해야 합니다.
QBOClient(on_refresh_token_rotated=...)를 구독하여 모든 순환을 캡처하세요. 자세한 내용은 SECURITY.md를 참조하세요.
~/.claude/claude_code_config.json(또는 프로젝트의 MCP 설정)에 추가하세요:
{
"mcpServers": {
"qbo": {
"command": "qbo-mcp",
"env": {
"QBO_CLIENT_ID": "ABxxxxxxxxxxxxxx",
"QBO_CLIENT_SECRET": "xxxxxxxxxxxxxxxx",
"QBO_REFRESH_TOKEN": "ABxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"QBO_REALM_ID": "1234567890123456",
"QBO_ENVIRONMENT": "production"
}
}
}
}Claude Code를 재시작합니다. 새로운 세션에서 8개의 qbo_* 도구가 나타납니다.
~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json(Windows)을 편집하고 위와 동일한 mcpServers 블록을 추가합니다. 데스크톱 앱을 재시작하세요.
모든 도구는 JSON 봉투를 반환합니다:
{ "ok": true, "data": { ... } }
{ "ok": false, "error": "human-readable message" }qbo_search_customersqbo_search_customers(query: str, limit: int = 50)Customer.DisplayName에 대한 부분 일치 검색입니다. 쿼리는 QBO의 쿼리 언어에 포함되기 전에 이스케이프 처리되므로 아포스트로피(O'Brien)와 밑줄(acme_test)은 안전합니다.
예시 응답:
{
"ok": true,
"data": {
"customers": [
{ "Id": "1001", "DisplayName": "Acme Corp", "Balance": 1250.00 }
],
"count": 1,
"query": "acme",
"limit": 50
}
}qbo_get_customerqbo_get_customer(customer_id: str)Id로 전체 고객 레코드를 가져옵니다. ID가 존재하지 않으면(404) data: null을 반환합니다.
qbo_search_vendors / qbo_get_vendor고객 쌍과 대칭적이며 Vendor 엔티티를 대상으로 합니다.
qbo_search_invoicesqbo_search_invoices(
date_from: str, # ISO date "YYYY-MM-DD"
date_to: str, # ISO date "YYYY-MM-DD"
status: str | None = None, # "open" | "paid" | None
limit: int = 200, # max 2000
)범위는 Invoice.TxnDate를 포함합니다. status 필터는 QBO의 Balance 필드에 대한 편의 기능입니다. "open"은 Balance > 0인 송장을, "paid"는 Balance = 0인 송장을 반환합니다.
페이지네이션은 투명하게 처리됩니다. QBO의 쿼리 엔드포인트는 명시적인 STARTPOSITION / MAXRESULTS 절을 요구하며, 클라이언트는 limit에 도달하거나 업스트림이 짧은 페이지를 반환할 때까지 페이지를 순회합니다. limit이 중단 조건이었을 경우 응답에 limit_reached: true가 포함됩니다.
qbo_get_invoiceqbo_get_invoice(invoice_id: str)전체 송장 레코드(Line[] 포함)를 반환하거나, 404인 경우 data: null을 반환합니다.
qbo_search_bills / qbo_get_invoice 패리티qbo_search_bills는 qbo_search_invoices와 동일하지만 Bill 엔티티(공급업체 측)를 대상으로 합니다. 동일한 날짜 의미론과 상태 필터를 사용합니다.
qbo_get_chart_of_accountsqbo_get_chart_of_accounts()영역 내의 모든 활성 계정을 반환합니다. 각 레코드에는 Id, Name, AccountType, AccountSubType, Classification, CurrentBalance 및 기타 QBO 필드가 포함됩니다. "이 거래가 어디에 게시되었는가?"와 같은 질문의 근거를 찾는 데 유용합니다.
git clone https://github.com/alveyautomation/qbo-mcp
cd qbo-mcp
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest # 50+ tests, ~3sPre-commit 훅 (gitleaks, trufflehog, ruff, formatter, tenant-fingerprint scrubber):
pip install pre-commit
pre-commit install실제 QBO 샌드박스 영역에 대한 통합 테스트는 QBO_INTEGRATION_TESTS=1로 제한됩니다. 일반적인 기여에는 필요하지 않습니다.
Failed to refresh QBO access token — 갱신 토큰이 무효화되었거나 앱의 client_id / client_secret이 잘못되었습니다. 갱신 토큰은 새 토큰이 발행되는 즉시 무효화되므로, 두 프로세스가 하나의 갱신 토큰을 공유하면 먼저 갱신하는 쪽이 승리합니다. 해결책: 순환된 토큰을 영구 저장하거나(on_refresh_token_rotated 참조), 갱신 토큰 자격 증명당 하나의 서버만 실행하세요.
Missing required environment variables — .env가 로드되기 전에 서버가 시작되었습니다. 부모 셸에서 변수를 export하거나 MCP 호스트 설정의 env 블록에 포함되어 있는지 확인하세요.
데이터가 있음에도 결과가 비어 있음 — QBO_ENVIRONMENT가 자격 증명과 일치하는지 확인하세요. 프로덕션 API 호스트에 샌드박스 갱신 토큰을 사용하면(또는 그 반대) 인증은 되지만 빈 회사가 반환됩니다.
긴 날짜 범위의 느린 속도 — QBO의 쿼리 엔드포인트는 페이지당 1000개 행으로 제한됩니다. 클라이언트가 페이지를 투명하게 순회하지만, 5년치 송장 스캔은 여전히 많은 왕복 통신을 의미합니다. date_from / date_to를 좁히거나 status로 필터링하는 것을 고려하세요.
Transient QBO error: HTTP 429 — Intuit의 속도 제한이 적용되었습니다. 클라이언트는 지수 백오프를 사용하여 자동으로 재시도합니다. 도구 출력에서 이 오류가 보이면 구성된 QBO_MAX_RETRIES를 초과한 것입니다. 값을 높이거나 쿼리 속도를 늦추세요.
이슈와 풀 리퀘스트를 환영합니다. 다음을 준수해 주세요:
PR을 열기 전에 pytest를 실행하세요 (pip install -e ".[dev]").
pre-commit run --all-files를 실행하세요.
v0.1 범위에 대한 추가 사항은 읽기 전용으로 유지하세요. 쓰기 엔드포인트는 v0.2에 포함됩니다.
테스트에는 합성 데이터만 사용하세요. 실제 고객 이름, 공급업체 이름 또는 영역 ID를 사용하지 마세요.
MIT — LICENSE를 참조하세요.
qbo-mcp는 비공식 타사 통합 도구입니다. Intuit Inc.의 보증, 제휴 또는 지원을 받지 않습니다. "QuickBooks" 및 "QuickBooks Online"은 Intuit Inc.의 상표입니다. 사용자의 책임하에 사용하시고, 프로덕션 의사결정에 의존하기 전에 귀하의 영역에서 동작을 확인하십시오.
Return the full chart of accounts (active only).
Returns:
JSON envelope. data.accounts is the list of account records,
each carrying Id, Name, AccountType, AccountSubType,
Classification, and CurrentBalance among other QBO fields.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden for behavioral disclosure. It mentions 'active only' filtering and the return envelope structure, which adds some value, but lacks details on authentication, rate limits, or pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two short sentences that front-load the purpose and immediately provide useful details about the return format. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list retrieval tool with no parameters and an output schema, the description adequately covers purpose and return structure. However, it could mention any potential limits or authentication requirements for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and schema coverage is 100%. The description does not need to explain parameters, and the baseline for no params is 4, which is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Return' and resource 'full chart of accounts', and specifies that it returns only active accounts, distinguishing it from siblings that focus on individual entities like customers or invoices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusion criteria. The decision must be inferred from tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full record for a single customer.
Args: customer_id: QBO Customer.Id (string-encoded integer per Intuit's API).
Returns:
JSON envelope. data is the customer record, or null on 404.
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the return envelope structure and that null is returned on 404, but lacks detail on side effects, auth needs, or rate limits. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with only three lines covering purpose, argument, and return behavior. It is well-structured using Args/Returns labels, and every sentence adds necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool, the description is complete: it specifies the input, the output envelope, and the null case. An output schema exists (as per signals) so detailed return fields are not required in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds significant value by specifying that customer_id is a 'string-encoded integer per Intuit's API'. This clarifies the expected format beyond the schema's simple type string.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch the full record for a single customer' with a specific verb and resource. It is distinct from sibling tools which target different entities (e.g., invoices, vendors) or search variants, leaving no ambiguity about its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when the agent needs a complete customer record by ID. While no explicit when-not or alternatives are given, the context is clear and the sibling tools cover other resources, so it adequately guides selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch full invoice detail including line items.
Args: invoice_id: QBO Invoice.Id.
Returns:
JSON envelope. data is the invoice record, or null on 404.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses a read operation returning null on 404, which is helpful. However, it omits any mention of permissions, rate limits, or side effects beyond the basic retrieval behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but structured with Args and Returns sections, and the main purpose is front-loaded. No extraneous text. It earns a high score for efficiency, though could be slightly more terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with an output schema (though not shown), the description covers the key behavior: fetching full details, handling 404, and the return envelope. It is complete enough for an agent to understand the tool's basic role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description states 'invoice_id: QBO Invoice.Id,' adding meaning that it is the identifier type. This partially compensates for the lack of schema descriptions, but no further details on format or constraints are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch full invoice detail including line items,' which is a specific verb and resource. It distinguishes from sibling tools like qbo_search_invoices (for listing) and qbo_get_customer (for different resource) by targeting a single invoice retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you have an invoice_id and need full details, but it does not explicitly contrast with search_invoices or provide when-not-to-use scenarios. No explicit guidance on alternatives is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full record for a single vendor.
Args: vendor_id: QBO Vendor.Id.
Returns:
JSON envelope. data is the vendor record, or null on 404.
| Name | Required | Description | Default |
|---|---|---|---|
| vendor_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses the return format (JSON envelope with 'data'), specifies null on 404, and implies read-only behavior. This provides sufficient transparency, though could mention idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus structured Args/Returns, front-loading the main purpose. Every sentence adds value with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description still provides essential details (null on 404) and parameter clarification. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds 'QBO Vendor.Id' to clarify the vendor_id parameter. This explains the exact value required, compensating for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch the full record for a single vendor', specifying the action, resource, and scope. It distinguishes from sibling QBO tools like qbo_search_vendors by focusing on a single vendor retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when a vendor ID is available, but does not explicitly state when to use this tool versus alternatives like qbo_search_vendors. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search vendor bills with TxnDate in [date_from, date_to] inclusive.
Args: date_from: ISO date (YYYY-MM-DD), start of TxnDate window. date_to: ISO date (YYYY-MM-DD), end of TxnDate window. status: Optional balance filter. "open" returns bills with a non-zero balance; "paid" returns bills with Balance == 0. Omit (null) for both. limit: Cap on yielded bills (1-2000, default 200).
Returns:
JSON envelope. data.bills is the list of bill records.
| Name | Required | Description | Default |
|---|---|---|---|
| date_from | Yes | ||
| date_to | Yes | ||
| status | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses return format ('JSON envelope. data.bills'), inclusive date range, optional status filter, and limit cap. This is fairly transparent for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args and Returns sections, but a bit verbose (7 lines). It is efficient enough and front-loads key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so description needn't detail return values, but it does mention the envelope. It covers all parameters and their constraints. Missing explicit error handling or pagination, but adequate for a simple search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so description compensates fully. It explains date_from and date_to as ISO dates with inclusive window, status options (open/paid/null), and limit range (1-2000, default 200), adding significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches vendor bills with a date range, specifying the resource and action. It distinguishes from siblings like qbo_search_invoices by focusing on bills.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (search bills by date range) and provides details on the status filter. It lacks explicit when-not-to-use or alternatives, but the context from sibling tools is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search customers by display name (substring, case-insensitive).
Args:
query: Free-text fragment matched against Customer.DisplayName
via QBO's LIKE '%query%' operator.
limit: Cap on returned customers (1-1000, default 50).
Returns: JSON envelope: {"ok": true, "data": {"customers": [...], "count": N}}.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the underlying LIKE operator and return envelope. No mention of authentication or rate limits, but these are less critical for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences plus structured Args/Returns. It is front-loaded with the purpose and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description still provides the return structure (JSON envelope) which is helpful. All aspects of the tool are addressed: purpose, parameters, and return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds full context: query is matched via LIKE operator, limit has range 1-1000 and default 50. This adds significant meaning beyond the schema's type declarations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search customers by display name (substring, case-insensitive)', specifying the verb, resource, and matching method. This distinguishes it from siblings like qbo_search_bills which search different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the parameters and their behavior, but does not explicitly state when to use this tool over alternatives. However, sibling tools operate on different entities, so usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search invoices created in [date_from, date_to] inclusive.
Args: date_from: ISO date (YYYY-MM-DD), start of TxnDate window. date_to: ISO date (YYYY-MM-DD), end of TxnDate window. status: Optional balance filter. "open" returns invoices with a non-zero balance; "paid" returns invoices with Balance == 0. Omit (null) for both. limit: Cap on yielded invoices (1-2000, default 200).
Returns:
JSON envelope. data.invoices is the list of invoice records.
| Name | Required | Description | Default |
|---|---|---|---|
| date_from | Yes | ||
| date_to | Yes | ||
| status | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear the full burden. It explains the status filter semantics (open vs paid) and return structure, but it does not disclose side effects, authentication needs, rate limits, or whether the operation is read-only. The description adds marginal behavioral context beyond the parameter list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with clear sections (Args and Returns). Each sentence adds necessary information without redundancy. It efficiently covers parameters and output structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters and an output schema, the description covers parameter semantics and return envelope. It lacks details on pagination, sorting, or error handling, but the output schema likely fills some gaps. For a search tool, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description explains the meaning, format, and defaults for all parameters: ISO dates for date_from/date_to, status optional values, limit cap and default. This adds significant meaning beyond the schema's titles and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool searches invoices by date range using 'Search invoices created in [date_from, date_to] inclusive.' It clearly identifies the resource (invoices) and action (search). However, it does not explicitly distinguish from sibling tools like qbo_search_bills, so it lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as qbo_get_invoice (single invoice) or qbo_search_bills (bills). There is no 'when-to-use' or 'when-not-to-use' language.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search vendors by display name (substring, case-insensitive).
Args: query: Free-text fragment matched against Vendor.DisplayName. limit: Cap on returned vendors (1-1000, default 50).
Returns: JSON envelope: {"ok": true, "data": {"vendors": [...], "count": N}}.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and adequately discloses the search behavior: substring, case-insensitive matching on DisplayName. It also specifies the return envelope format. However, it omits potential error conditions or limitations beyond the cap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a one-sentence purpose followed by structured Args and Returns sections. Every sentence adds value without redundancy, ideal for quick agent parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no nested objects) and the presence of an output schema (with return format described), the description covers the complete input-output contract. It includes the query behavior, parameter defaults, and response structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by explaining each parameter: 'Free-text fragment matched against Vendor.DisplayName' for query and 'Cap on returned vendors (1-1000, default 50)' for limit, adding essential meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Search vendors by display name (substring, case-insensitive)', providing a specific verb and resource with search criteria. It naturally distinguishes from sibling tools like qbo_get_vendor (single vendor fetch) and qbo_search_customers (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives such as qbo_get_vendor, qbo_search_customers, or qbo_search_invoices. It lacks explicit when-to-use or when-not-to-use instructions, leaving the agent to infer from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0qbo_get_chart_of_accountsqbo_get_customerqbo_get_invoiceqbo_get_vendorqbo_search_billsqbo_search_customersqbo_search_invoicesqbo_search_vendorsScored across 8 tools
Each tool targets a distinct entity or operation: get tools retrieve single records by ID, search tools list with filters, and chart of accounts is a separate list. No overlap in purpose.
All tools follow the consistent pattern `qbo_<verb>_<noun>` where verb is `get_` or `search_`, and nouns are plural for search (customers, vendors, invoices, bills) and singular or collective for get (customer, invoice, vendor, chart_of_accounts).
8 tools cover core QBO entities (accounts, customers, vendors, invoices, bills) without being overwhelming. The count is well-scoped for a focused accounting server.
Only read operations are provided (get and search). Missing critical mutation tools (create, update, delete) for any entity, which severely limits the server's utility for typical accounting workflows.
QuickBooks Online in Claude and ChatGPT: 221 tools, full ledger, multi-company, Canada + US, FR/EN.
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Hosted MCP server for Mini Accountant: invoices, expenses, customers, analytics, tax estimates.
