paperless-tax-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Rosehill
+
+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.

package/README.md

@@ -0,0 +1,87 @@
+# paperless-tax-mcp
+
+An **unofficial** MCP server for [paperless.tax](https://www.paperless.tax), the Israeli
+bookkeeping/expense platform.
+
+> ⚠️ Not affiliated with, endorsed by, or supported by Paperless. This talks to the app's
+> own private backend, not a published developer API, and can break without notice.
+> Use it against your own account.
+
+> 🚧 **Authentication is unresolved.** The self-service API key the UI issues is *not*
+> accepted as a bearer token on these endpoints — see
+> [`docs/api-surface.md`](docs/api-surface.md#authentication--unresolved). The server is
+> usable today only with a token taken from a logged-in browser session, which is
+> short-lived. Getting this to a durable credential is the project's main open problem;
+> help welcome.
+
+The value here is as much [`docs/api-surface.md`](docs/api-surface.md) as the code — no
+public documentation of this API exists anywhere, so the map is the point. The server
+grows as the surface gets documented.
+
+## Use
+
+Register with any MCP client — Claude Code, Claude Desktop, or a gateway. No install step:
+
+```json
+{
+  "mcpServers": {
+    "paperless-tax": {
+      "command": "npx",
+      "args": ["-y", "paperless-tax-mcp"],
+      "env": { "PAPERLESS_TOKEN": "..." }
+    }
+  }
+}
+```
+
+Claude Code, in one line:
+
+```bash
+claude mcp add paperless-tax --env PAPERLESS_TOKEN=... -- npx -y paperless-tax-mcp
+```
+
+### Configuration
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `PAPERLESS_TOKEN` | yes | Bearer token — see the auth caveat above |
+| `PAPERLESS_USER_ID` | no | 10-char account id; `whoami` discovers it |
+| `PAPERLESS_BASE_URL` | no | Defaults to `https://api.paperless.tax/` |
+
+### From source
+
+```bash
+npm install && npm run build && node dist/index.js
+```
+
+## Tools
+
+| Tool | Endpoint | Confidence |
+|---|---|---|
+| `whoami` | `GET users/get/params` | endpoint confirmed |
+| `pending_documents` | `GET documents/get/pending/{sUserID}` | endpoint confirmed |
+| `list_documents` | `POST bydate` | endpoint confirmed, body inferred |
+| `get_document` | `GET document/{id}` | inferred |
+| `get_download_url` | `POST downloadurl` | endpoint confirmed, response inferred |
+| `raw_request` | anything | escape hatch for mapping new surface |
+
+## Two things that will bite you
+
+Both are documented at length in `docs/api-surface.md`, and both cost real time to find:
+
+1. **`bydate` returns an empty list for a bad parameter, not an error.** A zero-document
+   response is indistinguishable from a genuinely empty range. Cross-check any count
+   against the web UI before believing it.
+2. **A 204 from this API is not success.** Send no credentials at all and you get the same
+   204. Control-test every auth scheme against a deliberately invalid credential.
+
+## Contributing
+
+Corrections to `docs/api-surface.md` are the most valuable contribution — especially
+anything that moves a row from *inferred* to *confirmed*, or that cracks authentication.
+Please mark what you verified versus what you assumed, and never include account
+identifiers, tokens, or ingest addresses in an issue or PR.
+
+## Licence
+
+MIT.

package/dist/client.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Minimal HTTP client for api.paperless.tax.
+ *
+ * Endpoint names were read out of the vendor's own Angular bundle; request and
+ * response *shapes* are largely inferred, so nothing here assumes a field exists.
+ * See docs/api-surface.md for what is confirmed versus guessed.
+ */
+export declare const DEFAULT_BASE_URL = "https://api.paperless.tax/";
+export declare class PaperlessError extends Error {
+    status?: number;
+    body?: string;
+    constructor(message: string, status?: number, body?: string);
+}
+/** 401/403 — see docs/api-surface.md §Authentication, which is unresolved. */
+export declare class PaperlessAuthError extends PaperlessError {
+    constructor(message: string, status?: number, body?: string);
+}
+export interface ClientOptions {
+    token?: string;
+    userId?: string;
+    baseUrl?: string;
+    minIntervalMs?: number;
+    timeoutMs?: number;
+    maxRetries?: number;
+}
+export declare class PaperlessClient {
+    private token?;
+    private userId?;
+    private baseUrl;
+    private minIntervalMs;
+    private timeoutMs;
+    private maxRetries;
+    private lastCall;
+    constructor(options?: ClientOptions);
+    buildUrl(...parts: string[]): string;
+    private throttle;
+    request(method: string, path: string, body?: unknown): Promise<unknown>;
+    getParams(): Promise<unknown>;
+    resolveUserId(): Promise<string>;
+    pending(): Promise<unknown>;
+    byDate(dateStart: string, dateEnd: string, docType?: number, extra?: Record<string, unknown>): Promise<unknown>;
+    document(docId: string): Promise<unknown>;
+    downloadUrl(docId: string, english?: boolean): Promise<unknown>;
+}
+/**
+ * Depth-first search for a key anywhere in a nested structure. Response
+ * envelopes are inconsistent between endpoints, so locating a field by name is
+ * more reliable than assuming a path.
+ */
+export declare function findKey(obj: unknown, key: string): unknown;

package/dist/client.js

@@ -0,0 +1,178 @@
+/**
+ * Minimal HTTP client for api.paperless.tax.
+ *
+ * Endpoint names were read out of the vendor's own Angular bundle; request and
+ * response *shapes* are largely inferred, so nothing here assumes a field exists.
+ * See docs/api-surface.md for what is confirmed versus guessed.
+ */
+export const DEFAULT_BASE_URL = "https://api.paperless.tax/";
+/**
+ * The SPA's auth interceptor skips these hosts, so neither do we — a presigned
+ * S3 GET rejects an Authorization header it did not sign for.
+ */
+const UNAUTHENTICATED_HOSTS = ["s3-eu-west-1.amazonaws.com"];
+export class PaperlessError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = "PaperlessError";
+        this.status = status;
+        this.body = body;
+    }
+}
+/** 401/403 — see docs/api-surface.md §Authentication, which is unresolved. */
+export class PaperlessAuthError extends PaperlessError {
+    constructor(message, status, body) {
+        super(message, status, body);
+        this.name = "PaperlessAuthError";
+    }
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class PaperlessClient {
+    token;
+    userId;
+    baseUrl;
+    minIntervalMs;
+    timeoutMs;
+    maxRetries;
+    lastCall = 0;
+    constructor(options = {}) {
+        this.token = options.token ?? process.env.PAPERLESS_TOKEN;
+        this.userId = options.userId ?? process.env.PAPERLESS_USER_ID;
+        const base = options.baseUrl ?? process.env.PAPERLESS_BASE_URL ?? DEFAULT_BASE_URL;
+        this.baseUrl = base.replace(/\/+$/, "") + "/";
+        this.minIntervalMs = options.minIntervalMs ?? 500;
+        this.timeoutMs = options.timeoutMs ?? 60_000;
+        this.maxRetries = options.maxRetries ?? 3;
+    }
+    buildUrl(...parts) {
+        return this.baseUrl + parts.filter(Boolean).map((p) => p.replace(/^\/+|\/+$/g, "")).join("/");
+    }
+    async throttle() {
+        const elapsed = Date.now() - this.lastCall;
+        if (elapsed < this.minIntervalMs)
+            await sleep(this.minIntervalMs - elapsed);
+        this.lastCall = Date.now();
+    }
+    async request(method, path, body) {
+        const url = path.startsWith("http") ? path : this.baseUrl + path.replace(/^\/+/, "");
+        if (!this.token) {
+            throw new PaperlessAuthError("No token — set PAPERLESS_TOKEN");
+        }
+        const headers = {
+            Accept: "application/json, text/plain, */*",
+            Origin: "https://www.paperless.tax",
+            Referer: "https://www.paperless.tax/",
+            "User-Agent": "paperless-tax-mcp (unofficial)",
+        };
+        if (!UNAUTHENTICATED_HOSTS.some((host) => url.includes(host))) {
+            headers["Authorization"] = `Bearer ${this.token}`;
+        }
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        let lastError;
+        for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+            await this.throttle();
+            let response;
+            try {
+                response = await fetch(url, {
+                    method: method.toUpperCase(),
+                    headers,
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                    signal: AbortSignal.timeout(this.timeoutMs),
+                });
+            }
+            catch (error) {
+                lastError = error;
+                await sleep(2 ** attempt * 1000);
+                continue;
+            }
+            if (response.status === 401 || response.status === 403) {
+                throw new PaperlessAuthError(`${response.status} from ${url}. A self-service API key is NOT accepted here — ` +
+                    "see docs/api-surface.md §Authentication.", response.status, (await response.text()).slice(0, 1000));
+            }
+            if (response.status >= 500) {
+                lastError = new PaperlessError(`${response.status} from ${url}`, response.status);
+                await sleep(2 ** attempt * 1000);
+                continue;
+            }
+            if (response.status >= 400) {
+                throw new PaperlessError(`${response.status} from ${url}: ${(await response.text()).slice(0, 400)}`, response.status);
+            }
+            const text = await response.text();
+            if (!text)
+                return null;
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return text;
+            }
+        }
+        throw new PaperlessError(`${url} failed after ${this.maxRetries} attempts: ${lastError}`);
+    }
+    // ------------------------------------------------------------- endpoints
+    getParams() {
+        return this.request("GET", this.buildUrl("users", "get", "params"));
+    }
+    async resolveUserId() {
+        if (this.userId)
+            return this.userId;
+        const found = findKey(await this.getParams(), "sUserID");
+        if (!found)
+            throw new PaperlessError("sUserID not found; set PAPERLESS_USER_ID");
+        this.userId = String(found);
+        return this.userId;
+    }
+    async pending() {
+        const uid = await this.resolveUserId();
+        return this.request("GET", this.buildUrl("documents", "get", "pending", uid));
+    }
+    async byDate(dateStart, dateEnd, docType, extra = {}) {
+        const payload = {
+            sUserID: await this.resolveUserId(),
+            sDateStart: dateStart,
+            sDateEnd: dateEnd,
+            ...extra,
+        };
+        if (docType !== undefined)
+            payload.iType = docType;
+        return this.request("POST", this.buildUrl("bydate"), payload);
+    }
+    document(docId) {
+        return this.request("GET", this.buildUrl("document", docId));
+    }
+    downloadUrl(docId, english = false) {
+        return this.request("POST", this.buildUrl("downloadurl"), {
+            sDocID: docId,
+            bIsEng: english,
+        });
+    }
+}
+/**
+ * Depth-first search for a key anywhere in a nested structure. Response
+ * envelopes are inconsistent between endpoints, so locating a field by name is
+ * more reliable than assuming a path.
+ */
+export function findKey(obj, key) {
+    if (Array.isArray(obj)) {
+        for (const item of obj) {
+            const found = findKey(item, key);
+            if (found)
+                return found;
+        }
+    }
+    else if (obj && typeof obj === "object") {
+        const record = obj;
+        if (record[key])
+            return record[key];
+        for (const value of Object.values(record)) {
+            const found = findKey(value, key);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    await server.connect(new StdioServerTransport());
+}
+main().catch((error) => {
+    // stdout carries the protocol, so diagnostics must go to stderr.
+    console.error("paperless-tax-mcp failed to start:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;AACnD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,iEAAiE;IACjE,OAAO,CAAC,KAAK,CAAC,oCAAoC,EAAE,KAAK,CAAC,CAAC;IAC3D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,9 @@
+/**
+ * MCP server exposing the paperless.tax backend.
+ *
+ * Tool descriptions track what is actually confirmed about the API. Where a
+ * request shape is inferred, the description says so — an agent calling these
+ * should know which results to trust and which to sanity-check.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,80 @@
+/**
+ * MCP server exposing the paperless.tax backend.
+ *
+ * Tool descriptions track what is actually confirmed about the API. Where a
+ * request shape is inferred, the description says so — an agent calling these
+ * should know which results to trust and which to sanity-check.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { PaperlessClient, PaperlessError } from "./client.js";
+let client;
+function getClient() {
+    if (!client)
+        client = new PaperlessClient();
+    return client;
+}
+function text(value, isError = false) {
+    return { content: [{ type: "text", text: value }], isError: isError || undefined };
+}
+/** Every tool reports failure as text rather than throwing, so an agent can react. */
+async function call(fn) {
+    try {
+        return text(JSON.stringify(await fn(), null, 2));
+    }
+    catch (error) {
+        if (error instanceof PaperlessError)
+            return text(`error: ${error.message}`, true);
+        return text(`error: ${error instanceof Error ? error.message : String(error)}`, true);
+    }
+}
+export function createServer() {
+    const server = new McpServer({ name: "paperless-tax", version: "0.1.0" });
+    server.tool("whoami", "Fetch account context from `users/get/params`. Confirmed endpoint. Use this first — " +
+        "it is the cheapest check that the configured token is actually accepted.", {}, () => call(() => getClient().getParams()));
+    server.tool("list_documents", "List documents in a date range via `POST bydate`. Endpoint confirmed; the request " +
+        "body is INFERRED (sUserID, sDateStart, sDateEnd, optional iType) and dates are " +
+        "assumed YYYY-MM-DD. An empty result may mean the range is genuinely empty OR that " +
+        "a parameter name is wrong — this API answers a bad parameter with an empty list " +
+        "rather than an error. Verify a non-empty range against the web UI before trusting " +
+        "a count.", {
+        date_start: z.string().describe("Start date, assumed YYYY-MM-DD"),
+        date_end: z.string().describe("End date, assumed YYYY-MM-DD"),
+        doc_type: z.number().int().optional().describe("iType filter; meaning not yet mapped"),
+    }, ({ date_start, date_end, doc_type }) => call(() => getClient().byDate(date_start, date_end, doc_type)));
+    server.tool("get_document", "Fetch one document's detail via `GET document/{id}`. Response shape inferred.", { doc_id: z.string().describe("sDocID") }, ({ doc_id }) => call(() => getClient().document(doc_id)));
+    server.tool("get_download_url", "Resolve a document to a fetchable URL via `POST downloadurl`. Returns a presigned S3 " +
+        "URL that expires. Do not send an Authorization header when fetching it — the " +
+        "signature does not cover one.", {
+        doc_id: z.string().describe("sDocID"),
+        english: z.boolean().optional().describe("bIsEng — request the English rendering"),
+    }, ({ doc_id, english }) => call(() => getClient().downloadUrl(doc_id, english ?? false)));
+    server.tool("pending_documents", "List uploaded-but-unfiled documents via `GET documents/get/pending/{sUserID}`.", {}, () => call(() => getClient().pending()));
+    server.tool("raw_request", "Call an arbitrary endpoint — the escape hatch for mapping unknown surface. `path` is " +
+        "relative to the API base (e.g. `documents/get/search`). Prefer a named tool where " +
+        "one exists. Pass sUserID as the literal \"auto\" to have it filled in.", {
+        method: z.string().describe("GET or POST"),
+        path: z.string().describe("Path relative to https://api.paperless.tax/"),
+        body: z.string().optional().describe("JSON request body as a string"),
+    }, async ({ method, path, body }) => {
+        let payload;
+        if (body) {
+            try {
+                payload = JSON.parse(body);
+            }
+            catch (error) {
+                return text(`error: body is not valid JSON: ${error}`, true);
+            }
+        }
+        return call(async () => {
+            if (payload && typeof payload === "object") {
+                const record = payload;
+                if (record.sUserID === "auto")
+                    record.sUserID = await getClient().resolveUserId();
+            }
+            return getClient().request(method, path, payload);
+        });
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/docs/api-surface.md

@@ -0,0 +1,119 @@
+# paperless.tax API surface
+
+What is known about the private backend behind [paperless.tax](https://www.paperless.tax),
+an Israeli bookkeeping/expense SaaS. There is **no public API documentation** for this
+service — searched 2026-07-25, nothing exists. Everything here was derived by reading the
+app's own Angular bundle and by probing the live API.
+
+Each claim is marked **confirmed** (observed against the live API or read directly from
+the shipped bundle) or **inferred** (a reasonable guess not yet verified). Account
+identifiers are redacted throughout.
+
+- **Base URL:** `https://api.paperless.tax/` — confirmed
+- **Front door:** Azure (responses carry `x-azure-ref`) — confirmed
+- **Web app:** `https://www.paperless.tax`, Angular SPA — confirmed
+- **Verified on:** 2026-07-25
+
+---
+
+## Authentication — UNRESOLVED
+
+This is the open problem. Summary of what was established on 2026-07-25:
+
+| Attempt | Result |
+|---|---|
+| `Authorization: Bearer <self-service API key>` | **401** `UnauthorizedAccessException` |
+| `Authorization: <key>` (no scheme) | 401 |
+| `Authorization: Token <key>` / `ApiKey <key>` | 401 |
+| `x-api-key`, `apikey`, `X-API-KEY`, `token` headers | 204 — **but see below** |
+
+**The 204 is a trap.** A bogus key and *no credentials at all* produce the identical
+204-with-no-body. It is an edge behaviour when no `Authorization` header is present, not a
+successful call. Any client that treats 204 as success will silently "succeed" at nothing.
+Always control-test an auth scheme against a deliberately invalid credential.
+
+So: `Authorization` is the header the backend actually reads, and the **self-service API
+key issued by the UI's API/webhooks settings modal (`POST getapikey`) is not accepted as a
+bearer token on the SPA's own endpoints.**
+
+Leading hypothesis (untested): that key is for *inbound* verification — the value Paperless
+signs its outgoing webhook calls with — rather than a credential for calling the API. The
+key and the webhook configuration are issued by the same settings modal, which is at least
+consistent with this.
+
+What is known to work: the bearer token the SPA itself holds after login authenticates
+these endpoints. Login is passwordless — email, then an SMS one-time code — so that token
+is short-lived and cannot be obtained non-interactively.
+
+`/api/…` and `/v1/…` prefixes return **404**; there is no separate versioned surface.
+Contributions establishing a durable auth path are very welcome.
+
+---
+
+## Endpoints
+
+Existence is confirmed for anything returning 401 rather than 404 — the route is real and
+merely refused.
+
+| Method | Path | Purpose | Confidence |
+|---|---|---|---|
+| GET | `users/get/params` | Account context loaded on app boot | endpoint confirmed |
+| GET | `documents/get/pending/{sUserID}` | Uploaded but not yet filed | endpoint confirmed |
+| POST | `bydate` | List documents over a date range | endpoint confirmed, body inferred |
+| POST | `documents/get/search` | Full document search | inferred |
+| POST | `documents/get/review` | Documents awaiting review | inferred |
+| GET | `document/{id}` | Single document detail | inferred |
+| POST | `downloadurl` | Resolve a document to a fetchable URL | endpoint confirmed, response inferred |
+| POST | `getapikey` | Issue the self-service API key | confirmed from bundle |
+| POST | `setapiwebhooks` | Configure webhook targets | confirmed from bundle |
+| — | `export/*` | MOVEIN / BKMV (מבנה אחיד) exports | confirmed from bundle |
+
+### `POST bydate` — inferred body
+
+```json
+{ "sUserID": "<10-char opaque id>", "sDateStart": "2025-01-01", "sDateEnd": "2025-12-31", "iType": 0 }
+```
+
+Date format is assumed ISO. **An unrecognised parameter yields an empty list, not an
+error** — the single most important gotcha here. A zero-document response is
+indistinguishable from a genuinely empty range unless cross-checked against the UI.
+
+### `POST downloadurl`
+
+```json
+{ "sDocID": "<doc id>", "bIsEng": false }
+```
+
+Returns a presigned URL on `s3-eu-west-1.amazonaws.com`. **Do not send an `Authorization`
+header** when fetching it — the signature does not cover one, and the request will be
+rejected. The SPA's own auth interceptor skips that host, which is what confirms the
+mechanism.
+
+---
+
+## Field naming
+
+Hungarian-ish prefixes throughout: `s` string, `i` integer, `b` boolean, `d` date,
+`a` array. Observed: `sUserID`, `sDocID`, `sKey`, `sBucketName`, `iType`, `bIsEng`,
+`iCode`, `sMessage`, `aParams`.
+
+`sUserID` is a 10-character opaque account id — **not** the business VAT number.
+
+Error envelope:
+
+```json
+{ "iCode": -1, "aParams": ["UnauthorizedAccessException"], "sMessage": "Unauthorized Exception occurred" }
+```
+
+## Other integration surfaces
+
+Documents can be ingested by **email**: each account gets an address at
+`mail.paperless.tax`, in both a shared and an account-scoped form. Anyone who knows the
+account-scoped address can post documents into that ledger, so treat it as a secret.
+
+## Prefer the sanctioned export where it fits
+
+The UI can produce a **MOVEIN / BKMV (מבנה אחיד)** export — the Israeli Tax Authority's
+uniform structure, ingestible by every Israeli accounting system and not dependent on a
+reverse-engineered API. Whether it carries original file attachments is an open question.
+Use the API for what that export does not cover.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "paperless-tax-mcp",
+  "version": "0.1.0",
+  "description": "Unofficial MCP server for paperless.tax, the Israeli bookkeeping platform",
+  "type": "module",
+  "bin": {
+    "paperless-tax-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "paperless",
+    "paperless.tax",
+    "bookkeeping",
+    "accounting",
+    "israel",
+    "expenses"
+  ],
+  "author": "Daniel Rosehill",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/danielrosehill/paperless-tax-mcp.git"
+  },
+  "homepage": "https://github.com/danielrosehill/paperless-tax-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/danielrosehill/paperless-tax-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.6.0"
+  }
+}