@desktopaccountingapi/quickbooks-desktop-mcp 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +142 -23
  2. package/package.json +2 -1
package/README.md CHANGED
@@ -1,78 +1,197 @@
1
1
  # Desktop Accounting API MCP server
2
2
 
3
- `@desktopaccountingapi/quickbooks-desktop-mcp` is the local [Model Context Protocol](https://modelcontextprotocol.io) server for [Desktop Accounting API](https://www.desktopaccountingapi.com/docs/), the REST API for QuickBooks Desktop. It lets Claude, Cursor, VS Code, Codex and other AI tools look up and change QuickBooks Desktop data in plain English: overdue invoices, a vendor's payment history, last month's profit and loss.
3
+ `@desktopaccountingapi/quickbooks-desktop-mcp` connects Claude, Cursor, VS Code, Codex and other AI tools to QuickBooks Desktop through [Desktop Accounting API](https://www.desktopaccountingapi.com/) and the [Model Context Protocol](https://modelcontextprotocol.io). Ask in plain English for overdue invoices, a vendor's payment history or last month's profit and loss, and the agent finds the operation, calls the API and answers from the company file.
4
4
 
5
- It runs over stdio with Node.js 20 or later on Windows, macOS and Linux, and has no runtime dependencies. It covers all 275 operations of API version 1.0.0.
5
+ - Covers all 275 operations of API 1.0.0 through five compact tools, so it does not fill the agent's context.
6
+ - Writes carry an idempotency key and are never retried blindly. Read-only keys are enforced by the API itself.
7
+ - Runs over stdio with Node.js 20 or later on Windows, macOS and Linux, with no runtime dependencies.
6
8
 
7
- If your client supports remote servers with a header, you can skip the install and use the hosted server at `https://mcp.desktopaccountingapi.com/`. Setup for every client: [MCP guide](https://www.desktopaccountingapi.com/docs/guides/mcp/).
9
+ The current version is **0.1.1**. [MCP guide](https://www.desktopaccountingapi.com/docs/guides/mcp/) · [Documentation](https://www.desktopaccountingapi.com/docs/) · [Changelog](CHANGELOG.md) · [Status](https://status.desktopaccountingapi.com)
10
+
11
+ ## Hosted server or local package
12
+
13
+ Both expose the same tools and call the same API with your secret key:
14
+
15
+ | | Hosted server | This package |
16
+ | --- | --- | --- |
17
+ | Address | `https://mcp.desktopaccountingapi.com/` (Streamable HTTP) | `npx -y @desktopaccountingapi/quickbooks-desktop-mcp` (stdio) |
18
+ | Install | Nothing | Node.js 20 or later |
19
+ | Secret key | `Authorization: Bearer sk_...` header | `DAAPI_SECRET_KEY` environment variable |
20
+ | Use it when | Your client supports remote servers with a header | Your client runs only local servers, or you prefer a local process |
21
+
22
+ ## Before you start
23
+
24
+ - Create a secret key in the [dashboard](https://www.desktopaccountingapi.com/dashboard) under **API keys**. Use a separate key per person or tool, so you can revoke one without affecting the rest. For tools that should only look things up, choose **Read-only** (see [Read-only access](#read-only-access)). Test projects issue `sk_test_...` keys, production projects `sk_live_...` keys.
25
+ - Connect at least one end user's QuickBooks Desktop company file. QuickBooks must be open on that computer for data requests to succeed.
26
+
27
+ Replace `sk_live_...` below with your key. Keep it in your client's configuration only, never in shared documents, chat or a repository.
8
28
 
9
29
  ## Setup
10
30
 
11
- You need a secret key from the dashboard (**API keys**) and at least one connected QuickBooks Desktop company file.
31
+ ### Claude Desktop
12
32
 
13
- Claude Desktop (`claude_desktop_config.json`, **Settings > Developer > Edit Config**):
33
+ Open **Settings > Developer > Edit Config** (`claude_desktop_config.json`) and add:
14
34
 
15
35
  ```json
16
36
  {
17
37
  "mcpServers": {
18
38
  "quickbooks-desktop": {
19
39
  "command": "npx",
20
- "args": ["-y", "@desktopaccountingapi/quickbooks-desktop-mcp"],
40
+ "args": ["-y", "@desktopaccountingapi/quickbooks-desktop-mcp@0.1.1"],
21
41
  "env": { "DAAPI_SECRET_KEY": "sk_live_..." }
22
42
  }
23
43
  }
24
44
  }
25
45
  ```
26
46
 
27
- Claude Code:
47
+ If the file already has an `mcpServers` section, add the `quickbooks-desktop` entry inside it, then restart Claude Desktop. Drop `@0.1.1` from the package name to always run the latest version.
48
+
49
+ ### Claude Code
28
50
 
29
51
  ```sh
30
52
  claude mcp add quickbooks-desktop --env DAAPI_SECRET_KEY=sk_live_... -- npx -y @desktopaccountingapi/quickbooks-desktop-mcp
31
53
  ```
32
54
 
33
- Any other stdio client: run `npx -y @desktopaccountingapi/quickbooks-desktop-mcp` with `DAAPI_SECRET_KEY` set.
55
+ Or the hosted server:
56
+
57
+ ```sh
58
+ claude mcp add --transport http quickbooks-desktop https://mcp.desktopaccountingapi.com/ --header "Authorization: Bearer sk_live_..."
59
+ ```
60
+
61
+ Add `--scope user` to make it available in all your projects.
62
+
63
+ ### Cursor
64
+
65
+ In `~/.cursor/mcp.json`, or `.cursor/mcp.json` inside a project:
66
+
67
+ ```json
68
+ {
69
+ "mcpServers": {
70
+ "quickbooks-desktop": {
71
+ "command": "npx",
72
+ "args": ["-y", "@desktopaccountingapi/quickbooks-desktop-mcp"],
73
+ "env": { "DAAPI_SECRET_KEY": "sk_live_..." }
74
+ }
75
+ }
76
+ }
77
+ ```
78
+
79
+ For the hosted server, replace `command`, `args` and `env` with `"url": "https://mcp.desktopaccountingapi.com/"` and `"headers": { "Authorization": "Bearer sk_live_..." }`.
80
+
81
+ ### VS Code
82
+
83
+ Run **MCP: Open User Configuration** from the Command Palette, or use `.vscode/mcp.json` in a workspace. The top-level key is `servers`:
84
+
85
+ ```json
86
+ {
87
+ "inputs": [{ "type": "promptString", "id": "daapi-key", "description": "Desktop Accounting API secret key", "password": true }],
88
+ "servers": {
89
+ "quickbooks-desktop": {
90
+ "type": "stdio",
91
+ "command": "npx",
92
+ "args": ["-y", "@desktopaccountingapi/quickbooks-desktop-mcp"],
93
+ "env": { "DAAPI_SECRET_KEY": "${input:daapi-key}" }
94
+ }
95
+ }
96
+ }
97
+ ```
98
+
99
+ VS Code asks for the key once and stores it securely, so it never sits in the file.
100
+
101
+ ### Other clients
102
+
103
+ Any stdio client: run `npx -y @desktopaccountingapi/quickbooks-desktop-mcp` with `DAAPI_SECRET_KEY` set. Any client that supports remote servers with custom headers can use `https://mcp.desktopaccountingapi.com/` with `Authorization: Bearer sk_live_...`. Setup for Codex CLI and more clients is in the [MCP guide](https://www.desktopaccountingapi.com/docs/guides/mcp/).
104
+
105
+ ### Verify it works
106
+
107
+ Ask the agent: "List my QuickBooks Desktop end users and show the 5 most recent invoices for the first one." If it returns real data from the company file, you are set up. The key is checked when the agent first requests data, so a "connected" indicator alone does not prove the key works.
34
108
 
35
109
  ## Options
36
110
 
37
111
  | Flag | Environment | Meaning |
38
112
  | --- | --- | --- |
39
- | | `DAAPI_SECRET_KEY` | Secret key (`sk_live_...` or `sk_test_...`). |
113
+ | | `DAAPI_SECRET_KEY` | Secret key (`sk_live_...` or `sk_test_...`). Required. |
40
114
  | `--read-only` | `DAAPI_MCP_READ_ONLY=true` | Hide and refuse operations that change data. |
41
115
  | `--resources invoices,customers` | `DAAPI_MCP_RESOURCES` | Also expose one tool per operation for these resources (`all` for every operation). |
42
- | `--end-user-id eu_...` | `DAAPI_END_USER_ID` | Default end user (company file) for QuickBooks operations. |
116
+ | `--end-user-id eu_...` | `DAAPI_END_USER_ID` | Default end user (company file) for QuickBooks operations. A tool call's `end_user_id` overrides it. |
43
117
  | `--base-url <url>` | `DAAPI_BASE_URL` | API origin. Default `https://api.desktopaccountingapi.com`. |
44
-
45
- For a limit the API itself enforces, create a **read-only** secret key in the dashboard. The API rejects every write made with it (`403 API_KEY_READ_ONLY`), whatever the client does.
118
+ | `--version` | | Print the version. |
119
+ | `--help` | | Print the options. |
46
120
 
47
121
  ## Tools
48
122
 
49
123
  | Tool | What it does |
50
124
  | --- | --- |
51
- | `list_end_users` | Your end users (one QuickBooks company file each) and their connection status. |
52
- | `list_api_endpoints` | Search the operations by resource, name or words. |
53
- | `get_api_endpoint_schema` | One operation's description and input schema. |
54
- | `invoke_api_endpoint` | Call an operation. Writes carry an `Idempotency-Key`; an unknown outcome is reported with recovery steps, never resent. |
55
- | `search_docs` | Search the documentation. |
125
+ | `list_end_users` | Your end users (one QuickBooks company file each), with connection status and QuickBooks company name. |
126
+ | `list_api_endpoints` | Searches the operations by resource, name or words, for example "open invoices" or "profit and loss". |
127
+ | `get_api_endpoint_schema` | One operation's description and the JSON Schema of its arguments. |
128
+ | `invoke_api_endpoint` | Calls an operation and returns its JSON result. `fields` (dot paths such as `["id", "refNumber"]`) trims each record. |
129
+ | `search_docs` | Searches the documentation, including the error codes. |
130
+
131
+ With `--resources`, each operation of those resources also becomes its own tool, such as `qbd_invoices_list` and `qbd_invoices_create`.
132
+
133
+ ## Writes and safety
134
+
135
+ - By default the agent can read and write. The server instructs agents to describe each write and get your confirmation first.
136
+ - Every write carries an `Idempotency-Key`, and the result shows it. Repeating a call with the same key returns the original result instead of writing twice.
137
+ - Nothing is retried automatically. When a write's outcome is unknown, the result tells the agent not to resend it and how to check the request instead.
138
+ - Errors include the `userFacingMessage` and `fixes` from the [error catalog](https://www.desktopaccountingapi.com/docs/errors/), so the agent can tell you what to do.
139
+ - Every call appears in the dashboard's request log, like any other API call.
140
+
141
+ ## Read-only access
142
+
143
+ Create a **read-only** secret key in the dashboard and use it in the setup above. The API enforces it for every client: a read-only key can call every `GET` operation and passthrough requests that contain only queries, and any other call returns `403 API_KEY_READ_ONLY` before anything reaches QuickBooks. Add `--read-only` (or `DAAPI_MCP_READ_ONLY=true`) to also hide write tools from the agent; the read-only key is what guarantees writes cannot happen.
56
144
 
57
145
  ## Use as a library
58
146
 
147
+ `handleMcpRequest(request, options)` serves Streamable HTTP from any runtime with web-standard `Request` and `Response`, such as Cloudflare Workers, Deno or Bun:
148
+
59
149
  ```ts
60
- import { McpServer, handleMcpRequest } from "@desktopaccountingapi/quickbooks-desktop-mcp";
150
+ import { buildCatalog, handleMcpRequest } from "@desktopaccountingapi/quickbooks-desktop-mcp";
151
+
152
+ // The tool catalog comes from the API's OpenAPI document, published with the documentation.
153
+ const spec = await (await fetch("https://www.desktopaccountingapi.com/docs/openapi.json")).json();
154
+ const catalog = buildCatalog(spec);
155
+
156
+ export default {
157
+ fetch: (request: Request): Promise<Response> =>
158
+ handleMcpRequest(request, { catalog, version: "1.0.0", apiBaseUrl: "https://api.desktopaccountingapi.com" }),
159
+ };
61
160
  ```
62
161
 
63
- `handleMcpRequest(request, options)` serves Streamable HTTP from any runtime with web-standard `Request` and `Response`.
162
+ Clients send their own secret key as `Authorization: Bearer sk_...`; the server passes it to the API unchanged. `McpServer` and `Tools` are exported for other transports.
163
+
164
+ ## Troubleshooting
165
+
166
+ - **"No secret key reached the MCP server".** `DAAPI_SECRET_KEY` (or the `Authorization` header for the hosted server) is missing or not passed through.
167
+ - **"The secret key ... is malformed".** The key was cut off or mistyped. Copy it again from the dashboard.
168
+ - **`API_KEY_INVALID`.** The key is unknown or was revoked. The message shows only the key's last four characters.
169
+ - **Requests fail with a QuickBooks error.** QuickBooks must be open on the end user's computer and the Web Connector must be running. See [troubleshooting](https://www.desktopaccountingapi.com/docs/troubleshooting/).
170
+
171
+ ## Versioning and changelog
64
172
 
65
- ## Versioning
173
+ - The package follows [semantic versioning](https://semver.org/) and is released together with the [Node.js](https://github.com/DesktopAccountingAPI/quickbooks-desktop-node), [Python](https://github.com/DesktopAccountingAPI/quickbooks-desktop-python), [.NET](https://github.com/DesktopAccountingAPI/quickbooks-desktop-dotnet) and [Java](https://github.com/DesktopAccountingAPI/quickbooks-desktop-java) SDKs, with the same version number.
174
+ - It is generated from the Desktop Accounting API contract (sha256 `1cc3058cecb5...` for this release) by the same pipeline as the SDKs.
175
+ - Every release is listed in [CHANGELOG.md](CHANGELOG.md) and tagged `v<version>` on GitHub.
66
176
 
67
- Generated from the Desktop Accounting API contract (sha256 `1cc3058cecb5`) by the same pipeline as the SDKs, and released in lockstep with them. See [CHANGELOG.md](CHANGELOG.md).
177
+ ## Support
178
+
179
+ - [MCP guide](https://www.desktopaccountingapi.com/docs/guides/mcp/), [documentation](https://www.desktopaccountingapi.com/docs/) and [status page](https://status.desktopaccountingapi.com).
180
+ - Bugs and feature requests for this package: [GitHub issues](https://github.com/DesktopAccountingAPI/quickbooks-desktop-mcp/issues).
181
+ - Questions about your account, keys, billing or a connection: [contact us](https://www.desktopaccountingapi.com/contact). Never send your secret key.
182
+ - Security reports: use **Report a vulnerability** on this repository's Security tab.
68
183
 
69
184
  ## Development
70
185
 
71
186
  ```sh
72
187
  mise install # pinned Node.js
73
- mise run check # install, typecheck, build, tests with the official MCP client, smoke test, package contents
188
+ mise run check # install, typecheck, build, tests with the official MCP client, README samples, smoke test, package contents
74
189
  ```
75
190
 
191
+ This README is generated; `mise run check` parses its JSON configuration blocks and type-checks its TypeScript sample against the build.
192
+
76
193
  ## License
77
194
 
78
- MIT
195
+ MIT. See [LICENSE](LICENSE).
196
+
197
+ QuickBooks is a registered trademark of Intuit Inc. Desktop Accounting API is an independent product and is not affiliated with, endorsed by, or approved by Intuit Inc.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@desktopaccountingapi/quickbooks-desktop-mcp",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Model Context Protocol (MCP) server for Desktop Accounting API: QuickBooks Desktop for Claude, Cursor, VS Code, Codex and other AI tools.",
5
5
  "license": "MIT",
6
6
  "author": "Desktop Accounting API",
@@ -53,6 +53,7 @@
53
53
  "typecheck": "tsc -p tsconfig.json",
54
54
  "test": "node --test \"test/*.test.ts\"",
55
55
  "smoke": "node scripts/smoke.mjs",
56
+ "test:readme": "node scripts/readme-samples.mjs --lang ts",
56
57
  "pack:check": "node scripts/check-pack.mjs"
57
58
  },
58
59
  "devDependencies": {