Install the following MCP server: https://github.com/vladxyz/informer-mcp and run the local setup screen for the API keys.

┌─ Administration ────────────────────────────── Remove ─┐
│  ALIAS                        COMPANY NAME             │
│  [ acme                ]      [ ACME BV           ]    │
│  Short handle you use         Optional, shown in       │
│  in prompts.                  tool descriptions.       │
│                                                        │
│  API KEY                      SECURITY CODE            │
│  [ •••••••••••••••••  ]      [ •••••••••••••••  ]     │
│                                                        │
│  ACCESS                                                │
│  [ Read and write   ▾ ]                                │
│  Read only hides every tool that changes this          │
│  client's books.                                       │
└────────────────────────────────────────────────────────┘

  [ Add administration ]   [ Verify & save ]   ☐ Save without verifying

npm run setup          # or: informer-mcp setup

{
  "administrations": {
    "acme":     { "label": "ACME BV",         "api_key": "...", "security_code": "..." },
    "bakkerij": { "label": "Bakkerij de Bol", "api_key": "...", "security_code": "...", "mode": "read-only" }
  }
}

list_sales_invoices({ "administration": "acme", "filter": "open" })

list_sales_invoices({ "administration": "all", "filter": "open", "records": 50 })
list_sales_invoices({ "administration": ["acme", "bakkerij"], "filter": "open" })

{
  "administrations": ["acme", "bakkerij"],
  "results": {
    "acme": { "pagination": { "total": 3 }, "invoices": [ ... ] },
    "bakkerij": { "error": "[bakkerij] HTTP 401: Authentication failed" }
  }
}

git clone https://github.com/vladxyz/informer-mcp.git
cd informer-mcp
npm install          # also builds dist/ via the prepare script
npm run setup        # opens a local page to enter your API credentials

npm run bundle          # writes informer-mcp.mcpb

{
  "mcpServers": {
    "informer": {
      "command": "node",
      "args": ["C:\\path\\to\\informer-mcp\\dist\\index.js"]
    }
  }
}

informer-mcp --read-only     # only the tools that read
informer-mcp --read-write    # the default: create, update and delete too

{
  "administrations": {
    "acme":     { "api_key": "...", "security_code": "..." },
    "bakkerij": { "api_key": "...", "security_code": "...", "mode": "read-only" }
  }
}

`list_administrations` 会报告每个客户端的实际模式，启动时的横幅信息会总结为：`read-write: acme, garage`。

## 配置

| 变量 | 默认值 | 说明 |
| ----------------------------------- | ------------------------------------ | --------------------------------------------------------------- |
| `INFORMER_API_KEY` | — | 单个账套的 API 密钥。 |
| `INFORMER_SECURITY_CODE` | — | 该账套的安全代码。 |
| `INFORMER_CONFIG_FILE` | `~/.informer-mcp.json` | JSON 文件，列出多个账套。如果不存在，由 `setup` 创建。 |
| `INFORMER_ADMINISTRATIONS` | — | 同一份 JSON，作为环境变量内联提供。按账套覆盖配置文件。 |
| `INFORMER_ADMINISTRATION_ALIAS` | `default` | 单个 `INFORMER_API_KEY` 组合的别名。 |
| `INFORMER_ADMINISTRATION_LABEL` | — | 该别名的可读名称。 |
| `INFORMER_ADMINISTRATION_MODE` | — | 该别名的 `read-only` 或 `read-write` 模式。 |
| `INFORMER_BASE_URL` | `https://api.informer.eu/v2` | 覆盖 API 根地址。 |
| `INFORMER_READ_ONLY` | `false` | `true` 时仅暴露读取工具，对所有账套生效。与 `--read-only` 相同。 |
| `INFORMER_TOOLS` | *(全部)* | 标签和/或工具名称的允许列表，以逗号分隔。 |
| `INFORMER_EXCLUDE_TOOLS` | *(无)* | 拒绝列表，在允许列表之后应用。 |
| `INFORMER_TIMEOUT_MS` | `30000` | 每个请求的超时时间。 |
| `INFORMER_MAX_RETRIES` | `2` | 对 408/429/5xx 和网络错误的重试次数。 |
| `INFORMER_MAX_RESPONSE_CHARS` | `100000` | 较长的工具结果会被截断并附上提示。在 fan-out 查询中平均分配。 |
| `INFORMER_FANOUT_CONCURRENCY` | `4` | fan-out 查询同时访问多少个账套。 |
| `INFORMER_AUTO_SETUP` | `true` | `false` 时，不会在未配置凭据时打开设置页面。 |
| `INFORMER_OPEN_BROWSER` | `true` | `false` 时，打印设置 URL 而不是启动浏览器。 |
| `INFORMER_SPEC_MAX_AGE_HOURS` | `24` | 缓存 API 描述在后台刷新前存放最旧多久。`0` 表示禁用。 |
| `INFORMER_SPEC_CACHE` | `~/.informer-mcp.spec.json` | 下载的 API 描述缓存所在位置。 |
| `INFORMER_SPEC_URL` | Informer 发布的文档 | 覆盖待下载的 API 描述。 |

过滤器可以接受 OpenAPI 标签或工具名称，并且匹配时不区分大小写，忽略标点：

```GXP14

## 使用

连接后，可以用自然语言提问：

* *"2026 年还有哪些销售发票未付？"* → 使用 `filter` 调用 `list_sales_invoices`
* *"为 ACME 创建一个 10 小时咨询、每小时 €125 的草稿发票。"* → 先用 `get_sales_invoice_options` 获取有效的科目/增值税/模板 ID，再调用 `create_sales_invoice`
* *"把发票 12345 以 PDF 下载到我的桌面。"* → 使用 `save_path` 调用 `get_sales_invoice_pdf`
* *"显示 2026 年第 6 期的资产负债表。"* → 调用 `get_balance_report`

### 值得了解的约定

* **明确选择账套。** 当配置了多个账套时，每个工具都接受 `administration: "<alias>"`。`list_administrations` 会把别名映射到公司，读取工具也接受列表或 `"all"`。
* **日期**始终是 `YYYY-MM-DD`。
* **列表工具是分页的**，通过 `page`（默认 1）和 `records`（默认 20）进行，并返回带 `total` 和 `pages` 的 `pagination` 对象。
* **请求负载放在单个 `body` 参数中。** 路径参数和查询参数仍留在顶层，因此 `update_relation` 接受 `{ "id": 42, "body": { ... } }`。
* **创建单据时先调用 `*_options` 工具。** `get_sales_invoice_options`、`get_quotation_options` 等会返回你的账套当前有效的科目、VAT、模板、币种和付款条件 ID。
* **报表需要显式区间。** `get_balance_report` 需要 `year_from`、`year_to` 和 `period`；`get_column_balance_report` 还需要一个总账科目范围。

### PDF 与附件

Informer 会在 JSON 中以 base64 返回文件。实现此功能的工具（`get_*_pdf`、`download_sales_invoice_attachment`）接受可选的 `save_path`：

* **带 `save_path`** — 文件会被解码并写入该路径，工具返回 `{ saved_to, filename, bytes, mime_type }`；
* **不带 `save_path`** — 文件会以正确的 MIME 类型作为内联 MCP 资源返回；对大型文档来说，这可能会在上下文中开销很大。

上传方式相反：`upload_sales_invoice_attachment` 接受 `{ filename, file }`，其中 `file` 是 base64 编码的内容（最大 10 MB；支持 PDF、PNG、JPEG、GIF、DOC(X)、XLS(X)）。

## 工具参考

`npm run tools` 会根据当前 spec 打印此列表；`npm run tools -- --md` 会重新生成下面的表格。

除了各端点工具之外，服务器还提供三个工具：

| 工具 | 说明 |
| ----------------------------- | ------------------------------------------------------------------------------------ |
| `list_administrations` | 已配置哪些客户端账套、它们对应的公司，以及哪些可以写入。 |
| `open_setup` | 打开用于添加、更改或删除账套及其凭据的本地页面。 |
| `refresh_api_spec` | 重新读取 Informer 的 API 描述并更新工具。 |

<details>
<summary><strong>按 API 区域分组的全部 68 个端点工具</strong></summary>

### 账套

| 工具                   | 端点                     | 说明                   |
| ---------------------- | ------------------------ | ---------------------- |
| `get_administration`   | `GET /administration`    | 获取账套详情           |

### 往来单位

| 工具                | 端点                    | 说明                     |
| ------------------- | ----------------------- | ------------------------ |
| `get_relation`      | `GET /relations/{id}`   | 获取单个往来单位            |
| `update_relation`   | `PUT /relations/{id}`   | 更新往来单位                |
| `list_relations`    | `GET /relations`        | 获取往来单位列表            |
| `create_relation`   | `POST /relations`       | 创建新的往来单位            |

### 联系人

| 工具              | 端点                | 说明                 |
| ----------------- | ------------------- | -------------------- |
| `get_contact`     | `GET /contact/{id}` | 获取一个联系人         |
| `update_contact`  | `PUT /contact/{id}` | 更新联系人             |
| `create_contact`  | `POST /contact`     | 创建新的联系人         |

### 销售发票

| 工具                                        | 端点                                                    | 说明                                   |
| ------------------------------------------- | ------------------------------------------------------- | -------------------------------------- |
| `get_sales_invoice`                         | `GET /invoices/sales/{id}`                              | 获取一张销售发票                            |
| `update_sales_invoice`                      | `PUT /invoices/sales/{id}`                              | 更新销售发票                               |
| `list_sales_invoices`                       | `GET /invoices/sales`                                   | 获取销售发票列表                            |
| `create_sales_invoice`                      | `POST /invoices/sales`                                  | 创建新的销售发票                            |
| `get_sales_invoice_options`                 | `GET /invoices/sales/options`                           | 获取销售发票选项                            |
| `get_sales_invoice_pdf`                     | `GET /invoices/sales/pdf/{id}`                          | 获取销售发票 PDF                            |
| `send_sales_invoice`                        | `POST /invoices/sales/send/{id}`                        | 发送销售发票                               |
| `upload_sales_invoice_attachment`           | `POST /invoices/sales/{id}/attachments`                 | 上传发票专用附件                          |
| `download_sales_invoice_attachment`         | `GET /invoices/sales/{id}/attachments/{attachment_id}`  | 下载发票附件                                |
| `delete_sales_invoice_attachment`           | `DELETE /invoices/sales/{id}/attachments/{attachment_id}` | 删除发票专用附件                          |

### 采购发票

{
  "adopted": true,
  "api_version": "2.0.0",
  "endpoints": 49,
  "tools": 68,
  "changes": {
    "added":   [{ "tool": "list_projects", "endpoint": "GET /projects" }],
    "removed": [],
    "changed": [{ "tool": "create_sales_invoice", "endpoint": "POST /invoices/sales",
                  "notes": ["body now requires: project_id"] }],
    "unchanged": 66
  },
  "note": "The tool list has been updated; no restart is needed."
}

npm install         # install + build
npm run setup       # enter credentials in the browser
npm run bundle      # package as informer-mcp.mcpb for one-click install
npm run dev         # run from source with tsx
npm test            # vitest
npm run typecheck   # tsc --noEmit
npm run build       # compile to dist/
npm run tools       # print the tool surface
npm run update-spec # re-download openapi/api-docs.json and report added/removed paths

openapi/api-docs.json   vendored OpenAPI 3.0 document — the source of truth
src/openapi.ts          spec → operations: tool names, JSON Schema conversion
src/client.ts           HTTP client: auth headers, retries, error formatting
src/tools.ts            operations → MCP tools, filtering, result formatting
src/server.ts           server assembly (tools + openapi resource)
src/spec.ts             download, validate, cache and diff the OpenAPI document
src/setup.ts            local setup server: verify credentials, write the config file
src/setup-page.ts       the HTML it serves
src/index.ts            stdio entry point and CLI
manifest.json           extension manifest: entry point and install-time settings
scripts/update-spec.mjs refresh the vendored spec
scripts/list-tools.ts   print/regenerate the tool reference
scripts/bundle.mjs      stage production dependencies and pack the .mcpb