mcp-quickbooks 0.1.0__tar.gz

mcp_quickbooks-0.1.0/.dockerignore

@@ -0,0 +1,10 @@
+.git
+.venv
+__pycache__
+.pytest_cache
+.ruff_cache
+dist
+build
+*.egg-info
+.env
+.qbo_tokens.json

mcp_quickbooks-0.1.0/.env.example

@@ -0,0 +1,36 @@
+# Copy to .env and fill in with your Intuit Developer app credentials.
+# Never commit the filled-in .env; it is gitignored.
+
+# --- OAuth app credentials (from developer.intuit.com -> your app -> Keys & OAuth) ---
+QBO_CLIENT_ID=
+QBO_CLIENT_SECRET=
+
+# Must exactly match a redirect URI registered on the Intuit app.
+QBO_REDIRECT_URI=http://localhost:8765/callback
+
+# --- Target company ---
+# sandbox for the developer sandbox company, production for real books.
+QBO_ENVIRONMENT=sandbox
+# The company (realm) id. The auth flow captures this automatically; set it to pin a company.
+QBO_REALM_ID=
+
+# --- Least-privilege scopes (space-separated) ---
+# Default requests only the accounting scope. Add com.intuit.quickbooks.payment
+# only if you connect payment processing.
+QBO_SCOPES=com.intuit.quickbooks.accounting
+
+# --- Local token storage (gitignored) ---
+QBO_TOKEN_PATH=.qbo_tokens.json
+
+# --- Client-side rate limiting (kept under Intuit's throttles) ---
+QBO_REQUESTS_PER_MINUTE=450
+QBO_REQUESTS_PER_SECOND=8
+QBO_MAX_RETRIES=4
+
+# --- Streamable HTTP transport bind (only used by `mcp-quickbooks http`) ---
+QBO_HTTP_HOST=127.0.0.1
+QBO_HTTP_PORT=8000
+
+# --- Local loopback used by `mcp-quickbooks auth` to catch the OAuth redirect ---
+QBO_CALLBACK_HOST=localhost
+QBO_CALLBACK_PORT=8765

mcp_quickbooks-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Create venv and install
+        run: |
+          uv venv --python ${{ matrix.python-version }} .venv
+          uv pip install -e ".[dev]"
+
+      - name: Run tests
+        run: |
+          source .venv/bin/activate
+          pytest

mcp_quickbooks-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+node_modules/
+__pycache__/
+*.py[cod]
+.env
+.qbo_tokens.json
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.DS_Store

mcp_quickbooks-0.1.0/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "quickbooks": {
+      "command": "uvx",
+      "args": ["mcp-quickbooks", "stdio"]
+    }
+  }
+}

mcp_quickbooks-0.1.0/Dockerfile

@@ -0,0 +1,14 @@
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy
+
+WORKDIR /app
+
+COPY pyproject.toml README.md ./
+COPY src ./src
+
+RUN uv pip install --system --no-cache .
+
+ENTRYPOINT ["mcp-quickbooks", "stdio"]

mcp_quickbooks-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amin Ale
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_quickbooks-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: mcp-quickbooks
+Version: 0.1.0
+Summary: QuickBooks Online MCP server for invoices, customers, and payments. OAuth 2.1 + PKCE, stdio/HTTP.
+Author-email: Amin Ale <amin.ale.business@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: accounting,intuit,mcp,model-context-protocol,oauth,quickbooks,quickbooks-online,quickbooks-online-api
+Requires-Python: >=3.11
+Requires-Dist: anyio==4.14.2
+Requires-Dist: httpx==0.28.1
+Requires-Dist: mcp==1.28.1
+Requires-Dist: pydantic-settings==2.14.2
+Requires-Dist: pydantic==2.13.4
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio==1.3.0; extra == 'dev'
+Requires-Dist: pytest==9.1.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# QuickBooks Online MCP Server
+
+<!-- mcp-name: io.github.amin-ale/mcp-quickbooks -->
+
+[![CI](https://github.com/amin-ale/mcp-quickbooks/actions/workflows/ci.yml/badge.svg)](https://github.com/amin-ale/mcp-quickbooks/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+
+QuickBooks Online MCP server for Claude Desktop and any MCP client, written in Python on the official
+MCP SDK (FastMCP). It exposes 18 tools over invoices, customers, and payments (create, read, update,
+delete, list, search) plus read-only company and receivables resources, behind a real OAuth 2.1
+authorization-code + PKCE flow with automatic token refresh, client-side rate limiting that honors
+QuickBooks throttles, and structured errors that tell an agent what to do next. It runs over stdio and
+Streamable HTTP.
+
+Related: [HubSpot CRM MCP Server](https://github.com/amin-ale/hubspot-mcp-server) ·
+[MCP Audit Gateway](https://github.com/amin-ale/mcp-audit-gateway) ·
+[What production MCP actually requires](https://amin-ale.github.io/portfolio-site/what-production-mcp-actually-requires.html)
+
+## Architecture
+
+```mermaid
+flowchart LR
+    Agent["MCP client<br/>(Claude Desktop / HTTP)"]
+    subgraph Server["mcp-quickbooks (FastMCP)"]
+        Tools["18 tools<br/>invoices · customers · payments"]
+        Resources["resources<br/>company · receivables · customers"]
+        Client["QBOClient<br/>retry · backoff · error mapping"]
+        RL["RateLimiter<br/>per-second + per-minute buckets"]
+        Auth["AuthManager<br/>OAuth 2.1 + PKCE · token refresh"]
+        Store[("token store<br/>.qbo_tokens.json")]
+    end
+    QBO["Intuit QuickBooks Online API<br/>/v3/company/{realmId}"]
+
+    Agent <-->|stdio / streamable-http| Tools
+    Agent <-->|resources/read| Resources
+    Tools --> Client
+    Resources --> Client
+    Client --> RL
+    Client --> Auth
+    Auth <--> Store
+    Auth <-->|token + refresh| QBO
+    Client -->|REST + query| QBO
+```
+
+The server holds no state and stores no customer data: it is a stateless proxy over the QuickBooks REST API. Tokens live in a local file you control; the client deploys with its own Intuit credentials.
+
+## Tools
+
+Every tool returns a structured `{ "ok": true, ... }` result, or `{ "ok": false, "error": {...} }` with a `suggestion`. Each one carries MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) and a declared output schema.
+
+- `create_customer`: Create a customer. The display name must be unique; QuickBooks rejects duplicates with error 6240.
+- `get_customer`: Read one customer by Id, including balance, contact details, and the current SyncToken.
+- `update_customer`: Sparse update of an existing customer. Needs the Id and a fresh SyncToken.
+- `delete_customer`: Deactivate a customer (QuickBooks has no hard delete for customers), preserving history.
+- `list_customers`: List customers, most recently updated first, with caller-driven pagination.
+- `search_customers`: Find customers by display-name prefix, exact email, or active flag.
+- `create_invoice`: Create an invoice for an existing customer with one or more line items.
+- `get_invoice`: Read one invoice by Id, including lines, totals, balance, and the current SyncToken.
+- `update_invoice`: Replace an invoice. Lines are replaced wholesale, so send every line it should end with.
+- `delete_invoice`: Delete an invoice permanently. Needs the Id and a fresh SyncToken.
+- `list_invoices`: List invoices, most recent transaction date first, with caller-driven pagination.
+- `search_invoices`: Find invoices by customer Id, transaction-date range, or document number.
+- `create_payment`: Record a payment received, optionally applied against a specific invoice.
+- `get_payment`: Read one payment by Id, including linked transactions and the current SyncToken.
+- `update_payment`: Replace a payment. Dropping the invoice link reopens that invoice's balance.
+- `delete_payment`: Delete a payment permanently. Any invoice it settled goes back to unpaid.
+- `list_payments`: List payments, most recent transaction date first, with caller-driven pagination.
+- `search_payments`: Find payments by customer Id or transaction-date range.
+
+## Resources
+
+Read-only JSON:
+
+- `qbo://company`: company profile and legal address
+- `qbo://summary/receivables`: open/overdue invoice counts and outstanding balance
+- `qbo://summary/customers`: active customers ranked by outstanding balance
+
+## Least-privilege scopes
+
+The default scope is `com.intuit.quickbooks.accounting` only. Add `com.intuit.quickbooks.payment` (via `QBO_SCOPES`) solely if you connect payment processing. The scope string is validated at startup against the known Intuit scope set, so a typo fails fast rather than silently under-authorizing. Identity scopes (`openid`, `profile`, `email`) are never requested unless you opt in.
+
+## Rate limiting and retries
+
+A dual token-bucket limiter caps outbound traffic under both the QuickBooks per-second and per-minute ceilings (configurable via `QBO_REQUESTS_PER_SECOND` / `QBO_REQUESTS_PER_MINUTE`). On `429` the client honors the `Retry-After` header; on `429`/`5xx` without one it uses exponential backoff with jitter, up to `QBO_MAX_RETRIES`. A single `401` triggers a token refresh and one transparent retry.
+
+## Quickstart
+
+```bash
+uv venv --python 3.12 .venv
+uv pip install -e ".[dev]"
+
+cp .env.example .env       # fill in QBO_CLIENT_ID / QBO_CLIENT_SECRET
+mcp-quickbooks auth        # opens Intuit, captures the redirect, stores tokens
+mcp-quickbooks status      # verify the token refreshes
+
+mcp-quickbooks stdio       # run over stdio (Claude Desktop)
+mcp-quickbooks http --port 8000   # run over Streamable HTTP
+```
+
+Credentials are read lazily. The server starts, answers `initialize`, and serves `tools/list` with no `QBO_*` variables set at all; a tool call without credentials returns a structured `401` telling the caller what to configure. That keeps registry introspection and container smoke tests working without secrets.
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "quickbooks": {
+      "command": "mcp-quickbooks",
+      "args": ["stdio"],
+      "env": { "QBO_ENVIRONMENT": "sandbox" }
+    }
+  }
+}
+```
+
+### Docker
+
+```bash
+docker build -t mcp-quickbooks .
+docker run --rm -i --env-file .env mcp-quickbooks
+```
+
+## Running against a real Intuit sandbox
+
+1. Create an app at the [Intuit Developer portal](https://developer.intuit.com/) and open its **Keys & OAuth** section. Copy the **Development** client id and secret.
+2. Add a redirect URI that matches `QBO_REDIRECT_URI` in your `.env` (default `http://localhost:8765/callback`).
+3. Create a **sandbox company** from the developer dashboard; its company id is your `QBO_REALM_ID`.
+4. Set `QBO_ENVIRONMENT=sandbox`, fill in `QBO_CLIENT_ID` / `QBO_CLIENT_SECRET`, then run `mcp-quickbooks auth`. The browser flow returns a `realmId` automatically; it is stored alongside the tokens.
+5. `mcp-quickbooks status` confirms the tokens refresh. You are now driving the live sandbox.
+
+Switch `QBO_ENVIRONMENT=production` (with production keys and a connected company) to point at real books. Credentials and tokens are yours; nothing is committed: `.env` and `.qbo_tokens.json` are gitignored.
+
+## Tests
+
+The suite runs fully offline. Every QuickBooks and OAuth call is served by an in-memory fake (`tests/fake_qbo.py`) seeded from recorded-style fixtures in `tests/fixtures/`, wired in through an `httpx` mock transport: no network, no real credentials.
+
+```bash
+uv run pytest
+```
+
+## Registry metadata
+
+`server.json` describes the server for the MCP registry, and `.mcp.json` is the client-config snippet directory crawlers look for. **Publishing is intentionally left as a manual step.** See `PUBLISHING.md`. Nothing here submits to any registry.
+
+## Hire me
+
+I make AI-era and money-critical integrations production-safe: real auth, real rate limits, real error handling, real tests. Available for MCP server builds and API-integration hardening. Portfolio and contact: https://amin-ale.github.io/portfolio-site · amin.ale.business@gmail.com
+
+## License
+
+MIT: see [LICENSE](./LICENSE).

mcp_quickbooks-0.1.0/PUBLISHING.md

@@ -0,0 +1,71 @@
+# Publishing (manual)
+
+This repository ships registry metadata but **submits to nothing automatically**. Every step below is a deliberate human action.
+
+Order matters: PyPI comes first, because the MCP registry verifies package ownership by reading the `mcp-name:` marker off the live PyPI description page, and that description is this README.
+
+## 1. PyPI
+
+The `<!-- mcp-name: io.github.amin-ale/mcp-quickbooks -->` marker in `README.md` must be in place **before** the package is uploaded, and it must match the `name` field in `server.json` exactly.
+
+```bash
+uv build
+uv publish --token "$PYPI_TOKEN"
+```
+
+Then confirm the marker made it into the published description. It is an HTML comment, so the project page will not display it; check the raw description instead:
+
+```bash
+curl -s https://pypi.org/pypi/mcp-quickbooks/json | grep -c "mcp-name: io.github.amin-ale/mcp-quickbooks"
+```
+
+A count of 1 means the registry publish in step 3 will pass ownership verification; 0 means it will fail.
+
+## 2. server.json
+
+`server.json` targets the `2025-12-11` server schema. Constraints worth knowing before editing it: `title` and `description` are capped at 100 characters, `version` must be a plain semver string (ranges such as `^1.2.3` or `1.x` are rejected), and `name` takes exactly one slash.
+
+Validate it against the live endpoint before touching the publisher CLI. The endpoint is unauthenticated and has no side effects:
+
+```bash
+curl -s -X POST https://registry.modelcontextprotocol.io/v0/validate \
+  -H 'content-type: application/json' \
+  --data-binary @server.json
+```
+
+A pass returns `{"valid": true, "issues": []}`. A failure returns HTTP 422 with per-field errors.
+
+Keep `version` identical in `pyproject.toml` and `server.json`.
+
+## 3. MCP registry (registry.modelcontextprotocol.io)
+
+```bash
+brew install mcp-publisher
+mcp-publisher login github
+mcp-publisher validate
+mcp-publisher publish
+```
+
+`login github` runs a device-code flow: it prints a code to enter at https://github.com/login/device in a browser signed in as the account that owns the `io.github.<owner>` namespace. That GitHub login is the only namespace authorization mechanism; there is no separate registry account and no web upload form. The login token can expire mid-session, so a publish may need a fresh `login`.
+
+Confirm the listing:
+
+```bash
+curl -s -G https://registry.modelcontextprotocol.io/v0.1/servers --data-urlencode search=quickbooks
+```
+
+**Published version metadata is immutable and there is no unpublish.** A mistake in the name, description, or package identifier is fixed only by publishing a new version, and the wrong one stays visible. `mcp-publisher status` can mark a version deprecated, which is not the same as removing it. Get steps 1 and 2 right the first time.
+
+## 4. Other directories
+
+Other MCP directories take manual submissions, each with its own form and review queue. None of them is driven from this repository.
+
+## Pre-publish checklist
+
+- [ ] `uv run pytest` is green
+- [ ] `version` matches across `pyproject.toml` and `server.json`
+- [ ] The `mcp-name:` marker in `README.md` matches `server.json`'s `name`
+- [ ] `POST /v0/validate` returns `{"valid": true}`
+- [ ] README badges and links point at the real repository
+- [ ] `docker build -t mcp-quickbooks .` succeeds and the container answers `tools/list` with no credentials
+- [ ] No secrets committed (`.env`, `.qbo_tokens.json` stay ignored)

mcp_quickbooks-0.1.0/README.md

@@ -0,0 +1,152 @@
+# QuickBooks Online MCP Server
+
+<!-- mcp-name: io.github.amin-ale/mcp-quickbooks -->
+
+[![CI](https://github.com/amin-ale/mcp-quickbooks/actions/workflows/ci.yml/badge.svg)](https://github.com/amin-ale/mcp-quickbooks/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+
+QuickBooks Online MCP server for Claude Desktop and any MCP client, written in Python on the official
+MCP SDK (FastMCP). It exposes 18 tools over invoices, customers, and payments (create, read, update,
+delete, list, search) plus read-only company and receivables resources, behind a real OAuth 2.1
+authorization-code + PKCE flow with automatic token refresh, client-side rate limiting that honors
+QuickBooks throttles, and structured errors that tell an agent what to do next. It runs over stdio and
+Streamable HTTP.
+
+Related: [HubSpot CRM MCP Server](https://github.com/amin-ale/hubspot-mcp-server) ·
+[MCP Audit Gateway](https://github.com/amin-ale/mcp-audit-gateway) ·
+[What production MCP actually requires](https://amin-ale.github.io/portfolio-site/what-production-mcp-actually-requires.html)
+
+## Architecture
+
+```mermaid
+flowchart LR
+    Agent["MCP client<br/>(Claude Desktop / HTTP)"]
+    subgraph Server["mcp-quickbooks (FastMCP)"]
+        Tools["18 tools<br/>invoices · customers · payments"]
+        Resources["resources<br/>company · receivables · customers"]
+        Client["QBOClient<br/>retry · backoff · error mapping"]
+        RL["RateLimiter<br/>per-second + per-minute buckets"]
+        Auth["AuthManager<br/>OAuth 2.1 + PKCE · token refresh"]
+        Store[("token store<br/>.qbo_tokens.json")]
+    end
+    QBO["Intuit QuickBooks Online API<br/>/v3/company/{realmId}"]
+
+    Agent <-->|stdio / streamable-http| Tools
+    Agent <-->|resources/read| Resources
+    Tools --> Client
+    Resources --> Client
+    Client --> RL
+    Client --> Auth
+    Auth <--> Store
+    Auth <-->|token + refresh| QBO
+    Client -->|REST + query| QBO
+```
+
+The server holds no state and stores no customer data: it is a stateless proxy over the QuickBooks REST API. Tokens live in a local file you control; the client deploys with its own Intuit credentials.
+
+## Tools
+
+Every tool returns a structured `{ "ok": true, ... }` result, or `{ "ok": false, "error": {...} }` with a `suggestion`. Each one carries MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) and a declared output schema.
+
+- `create_customer`: Create a customer. The display name must be unique; QuickBooks rejects duplicates with error 6240.
+- `get_customer`: Read one customer by Id, including balance, contact details, and the current SyncToken.
+- `update_customer`: Sparse update of an existing customer. Needs the Id and a fresh SyncToken.
+- `delete_customer`: Deactivate a customer (QuickBooks has no hard delete for customers), preserving history.
+- `list_customers`: List customers, most recently updated first, with caller-driven pagination.
+- `search_customers`: Find customers by display-name prefix, exact email, or active flag.
+- `create_invoice`: Create an invoice for an existing customer with one or more line items.
+- `get_invoice`: Read one invoice by Id, including lines, totals, balance, and the current SyncToken.
+- `update_invoice`: Replace an invoice. Lines are replaced wholesale, so send every line it should end with.
+- `delete_invoice`: Delete an invoice permanently. Needs the Id and a fresh SyncToken.
+- `list_invoices`: List invoices, most recent transaction date first, with caller-driven pagination.
+- `search_invoices`: Find invoices by customer Id, transaction-date range, or document number.
+- `create_payment`: Record a payment received, optionally applied against a specific invoice.
+- `get_payment`: Read one payment by Id, including linked transactions and the current SyncToken.
+- `update_payment`: Replace a payment. Dropping the invoice link reopens that invoice's balance.
+- `delete_payment`: Delete a payment permanently. Any invoice it settled goes back to unpaid.
+- `list_payments`: List payments, most recent transaction date first, with caller-driven pagination.
+- `search_payments`: Find payments by customer Id or transaction-date range.
+
+## Resources
+
+Read-only JSON:
+
+- `qbo://company`: company profile and legal address
+- `qbo://summary/receivables`: open/overdue invoice counts and outstanding balance
+- `qbo://summary/customers`: active customers ranked by outstanding balance
+
+## Least-privilege scopes
+
+The default scope is `com.intuit.quickbooks.accounting` only. Add `com.intuit.quickbooks.payment` (via `QBO_SCOPES`) solely if you connect payment processing. The scope string is validated at startup against the known Intuit scope set, so a typo fails fast rather than silently under-authorizing. Identity scopes (`openid`, `profile`, `email`) are never requested unless you opt in.
+
+## Rate limiting and retries
+
+A dual token-bucket limiter caps outbound traffic under both the QuickBooks per-second and per-minute ceilings (configurable via `QBO_REQUESTS_PER_SECOND` / `QBO_REQUESTS_PER_MINUTE`). On `429` the client honors the `Retry-After` header; on `429`/`5xx` without one it uses exponential backoff with jitter, up to `QBO_MAX_RETRIES`. A single `401` triggers a token refresh and one transparent retry.
+
+## Quickstart
+
+```bash
+uv venv --python 3.12 .venv
+uv pip install -e ".[dev]"
+
+cp .env.example .env       # fill in QBO_CLIENT_ID / QBO_CLIENT_SECRET
+mcp-quickbooks auth        # opens Intuit, captures the redirect, stores tokens
+mcp-quickbooks status      # verify the token refreshes
+
+mcp-quickbooks stdio       # run over stdio (Claude Desktop)
+mcp-quickbooks http --port 8000   # run over Streamable HTTP
+```
+
+Credentials are read lazily. The server starts, answers `initialize`, and serves `tools/list` with no `QBO_*` variables set at all; a tool call without credentials returns a structured `401` telling the caller what to configure. That keeps registry introspection and container smoke tests working without secrets.
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "quickbooks": {
+      "command": "mcp-quickbooks",
+      "args": ["stdio"],
+      "env": { "QBO_ENVIRONMENT": "sandbox" }
+    }
+  }
+}
+```
+
+### Docker
+
+```bash
+docker build -t mcp-quickbooks .
+docker run --rm -i --env-file .env mcp-quickbooks
+```
+
+## Running against a real Intuit sandbox
+
+1. Create an app at the [Intuit Developer portal](https://developer.intuit.com/) and open its **Keys & OAuth** section. Copy the **Development** client id and secret.
+2. Add a redirect URI that matches `QBO_REDIRECT_URI` in your `.env` (default `http://localhost:8765/callback`).
+3. Create a **sandbox company** from the developer dashboard; its company id is your `QBO_REALM_ID`.
+4. Set `QBO_ENVIRONMENT=sandbox`, fill in `QBO_CLIENT_ID` / `QBO_CLIENT_SECRET`, then run `mcp-quickbooks auth`. The browser flow returns a `realmId` automatically; it is stored alongside the tokens.
+5. `mcp-quickbooks status` confirms the tokens refresh. You are now driving the live sandbox.
+
+Switch `QBO_ENVIRONMENT=production` (with production keys and a connected company) to point at real books. Credentials and tokens are yours; nothing is committed: `.env` and `.qbo_tokens.json` are gitignored.
+
+## Tests
+
+The suite runs fully offline. Every QuickBooks and OAuth call is served by an in-memory fake (`tests/fake_qbo.py`) seeded from recorded-style fixtures in `tests/fixtures/`, wired in through an `httpx` mock transport: no network, no real credentials.
+
+```bash
+uv run pytest
+```
+
+## Registry metadata
+
+`server.json` describes the server for the MCP registry, and `.mcp.json` is the client-config snippet directory crawlers look for. **Publishing is intentionally left as a manual step.** See `PUBLISHING.md`. Nothing here submits to any registry.
+
+## Hire me
+
+I make AI-era and money-critical integrations production-safe: real auth, real rate limits, real error handling, real tests. Available for MCP server builds and API-integration hardening. Portfolio and contact: https://amin-ale.github.io/portfolio-site · amin.ale.business@gmail.com
+
+## License
+
+MIT: see [LICENSE](./LICENSE).

mcp_quickbooks-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "mcp-quickbooks"
+version = "0.1.0"
+description = "QuickBooks Online MCP server for invoices, customers, and payments. OAuth 2.1 + PKCE, stdio/HTTP."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Amin Ale", email = "amin.ale.business@gmail.com" }]
+keywords = [
+    "mcp",
+    "quickbooks",
+    "quickbooks-online",
+    "quickbooks-online-api",
+    "intuit",
+    "accounting",
+    "oauth",
+    "model-context-protocol",
+]
+
+dependencies = [
+    "mcp==1.28.1",
+    "httpx==0.28.1",
+    "pydantic==2.13.4",
+    "pydantic-settings==2.14.2",
+    "anyio==4.14.2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest==9.1.1",
+    "pytest-asyncio==1.3.0",
+]
+
+[project.scripts]
+mcp-quickbooks = "mcp_quickbooks.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_quickbooks"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+addopts = "-q"

mcp_quickbooks-0.1.0/server.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.amin-ale/mcp-quickbooks",
+  "title": "QuickBooks Online MCP Server",
+  "description": "QuickBooks Online MCP server for invoices, customers, and payments. OAuth 2.1 + PKCE, stdio/HTTP.",
+  "version": "0.1.0",
+  "websiteUrl": "https://amin-ale.github.io/portfolio-site/offer-mcp.html",
+  "repository": {
+    "url": "https://github.com/amin-ale/mcp-quickbooks",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "mcp-quickbooks",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "runtimeArguments": [
+        {
+          "type": "positional",
+          "value": "stdio",
+          "isRequired": true,
+          "description": "Run the server over stdio."
+        }
+      ],
+      "environmentVariables": [
+        {
+          "name": "QBO_CLIENT_ID",
+          "description": "Intuit app client id.",
+          "isRequired": true,
+          "isSecret": true
+        },
+        {
+          "name": "QBO_CLIENT_SECRET",
+          "description": "Intuit app client secret.",
+          "isRequired": true,
+          "isSecret": true
+        },
+        {
+          "name": "QBO_ENVIRONMENT",
+          "description": "sandbox or production.",
+          "isRequired": false,
+          "default": "sandbox"
+        },
+        {
+          "name": "QBO_REALM_ID",
+          "description": "QuickBooks company (realm) id.",
+          "isRequired": false
+        },
+        {
+          "name": "QBO_SCOPES",
+          "description": "Space-separated OAuth scopes; defaults to accounting only.",
+          "isRequired": false,
+          "default": "com.intuit.quickbooks.accounting"
+        }
+      ]
+    }
+  ]
+}

mcp_quickbooks-0.1.0/src/mcp_quickbooks/__init__.py

@@ -0,0 +1,4 @@
+from .config import Settings, load_settings
+from .server import build_server
+
+__all__ = ["Settings", "load_settings", "build_server"]

mcp_quickbooks-0.1.0/src/mcp_quickbooks/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())