sevdesk-mcp

sevdesk-mcp

English · Deutsch

sevDesk の包括的な MCP サーバーです。すべての API エンドポイント、保護された書き込み機能、組み込みの簿記監査レイヤーを備えています。

Claude（または任意の MCP クライアント）を sevDesk アカウントに接続できます。伝票や請求書の一覧表示と作成、銀行取引の照合、151 件すべての API 操作へのアクセスが可能です。さらに、誤った仕訳とは何かを把握したうえで監査を実行できます。たとえば、海外の仕入先がリバースチャージ §13b ではなく国内 0 % で計上されている場合、勘定科目で認められていない税ルールが使われている場合、領収書のない支払いがある場合などです。

ステータス：v0.5.0。 実際の sevDesk アカウント（簿記システム 2.0）で検証済みです。監査では、まさにこのツールが検出するよう設計された種類の誤仕訳が見つかりました。CHANGELOG.md をご覧ください。

クイックスタート

必要なもの： Node.js ≥ 22、sevDesk アカウント、MCP クライアント（Claude Code、Claude Desktop など）。

1. API トークンを取得する

sevDesk で、Settings → Users → your user → API を開きます。トークンは 32 文字の 16 進数文字列です。

⚠️ sevDesk API トークンにスコープはありません。ログイン時に可能な操作はすべて実行できます。パスワードと同じように扱い、まずは読み取り専用モードで開始してください。

2. MCP クライアントを接続する

Claude Code — 次のコマンドを実行し、書き込まれた設定（~/.claude.json）に実際のトークンを入力します。

claude mcp add --scope user sevdesk \
  --env SEVDESK_API_TOKEN=REPLACE_ME \
  --env SEVDESK_READ_ONLY=true \
  -- npx -y sevdesk-mcp

Claude Desktop — claude_desktop_config.json に追加します（Settings → Developer → Edit Config）。

{
  "mcpServers": {
    "sevdesk": {
      "command": "npx",
      "args": ["-y", "sevdesk-mcp"],
      "env": {
        "SEVDESK_API_TOKEN": "your-token",
        "SEVDESK_READ_ONLY": "true"
      }
    }
  }
}

ほかの MCP クライアントも同様に動作します。stdio トランスポートを使用し、npx -y sevdesk-mcp（またはクローンから node dist/index.js）を実行して、環境変数で設定します。ソースから実行する場合は、次のコマンドを使用します。git clone https://github.com/joosthel/sevdesk-mcp && cd sevdesk-mcp && npm install && npm run build。

3. 初回実行

クライアントを再起動し、sevdesk_ping を実行するよう指示します。ok: true、簿記システムのバージョン（2.0 = taxRule、1.0 = 従来の taxType）、およびモード（READ-ONLY）が表示されます。その後、次のように質問できます。

• 「今年の VAT 監査を実行して、重大度の高い指摘事項をすべて説明してください。」
• 「米国のソフトウェアサブスクリプションはリバースチャージで計上されていますか？ 今四半期の §13b の課税標準額はいくらですか？」
• 「まだ領収書のない銀行支払いはどれですか？」
• 「取引先 1009 向けに、1 日 800 € のコンサルティングを 3 日分計上した請求書の下書きを作成してください。」（書き込みモードが必要です）
• 「税ルール 12 を使用できる勘定科目はどれですか？」
• 「sevDesk API を呼び出して、直近 10 件の注文を取得してください。」 — 汎用カタログを使えば、厳選されたツール以外のすべての操作も実行できます。

監査結果の例：

{
  "severity": "high",
  "code": "zero_rate_booked_as_domestic",
  "voucher": "2026-06-24 · Acme Cloud, Inc. · 88.03 EUR · #INV-2043",
  "detail": "Booked as \"Vorsteuerabziehbare Aufwendungen\" (taxRule 9) but every position carries 0 % VAT, and the supplier's contact is registered in \"us\".",
  "suggestion": "If this is a service from a supplier established abroad, it is Reverse Charge: taxRule 12 (§13b Abs. 2, with input-tax deduction) …"
}

4. 書き込みを有効にする（任意、後から設定）

設定を信頼できるようになったら、SEVDESK_READ_ONLY を "false" に設定し、クライアントを再起動します。すべての書き込みツールは dryRun を受け付け（グローバルな SEVDESK_DRY_RUN も適用されます）、実際に送信することなく、送信される内容を正確に表示します。書き込みの安全性 をご覧ください。

ツール

24 個のツールで、151 件すべての API 操作を網羅しています。

監査

ツール	内容
sevdesk_audit_vat	リバースチャージの誤った記帳、帳簿の反対側から適用されたルール、記帳先の勘定科目で認められていない税ルール、税ルールと矛盾する税率、合計の不一致、仕入先ごとの記帳の不整合を検出します。可能な場合は仕入先の連絡先に登録された国を使用します
sevdesk_reverse_charge_report	期間中の§13bの課税標準額を集計します。相殺されてゼロになるもの（ルール12/14）、実際に納付するもの（ルール13）、自社の売上（ルール5）に分けて表示します
sevdesk_find_duplicates	重複する書類番号、N日以内に同じ仕入先・金額で登録されたもの、Entwurfのまま残っている証憑を検出します
sevdesk_subscription_gaps	仕入先ごとに月次の周期を検出し、抜けている月を報告します
sevdesk_diff_receipt_folder	証憑PDFのローカルフォルダーと記帳済みの証憑を双方向で照合します（SEVDESK_RECEIPT_DIRSが必要です）
sevdesk_reconcile_transactions	金額と日付の近さから銀行取引と証憑を照合します。領収書のない支払い、支払いのない証憑を検出します
sevdesk_invoice_aging	未払いの請求書を支払期限超過日数ごとに分類し、部分入金後の残額や、送付されていないままの下書きを表示します

日常業務

sevdesk_ping · sevdesk_summarize · sevdesk_list_vouchers · sevdesk_get_voucher · sevdesk_list_invoices · sevdesk_list_contacts · sevdesk_list_transactions · sevdesk_receipt_guidance · sevdesk_upload_voucher_file · sevdesk_create_voucher · sevdesk_set_tax_rule · sevdesk_create_invoice · sevdesk_get_invoice_pdf · sevdesk_mark_invoice_sent

特長：sevdesk_summarizeは請求書または証憑をサーバー側で集計します。月、ステータス、連絡先ごとに件数と税抜・税額・税込の合計をまとめるため、台帳の規模にかかわらず、「第2四半期の売上」や「仕入先別の経費」といった質問に数百トークンで回答できます。sevdesk_receipt_guidanceは、sevDesk独自の検証テーブルに基づいて、「sevDeskで実際に受け付けられる記帳先の勘定科目／税ルール／税率の組み合わせ」を回答します。sevdesk_set_tax_ruleはガードレールを設けたうえで、下書きの証憑を別のVATルールに付け替えます。sevdesk_create_invoiceが作成するのは常に下書きで、確認せずに顧客へ送信されることはありません。sevdesk_get_invoice_pdfは請求書の送信状態を変更せずに、生成済みのPDFを保存します。

全機能への対応

sevdesk_list_operations · sevdesk_describe_operation · sevdesk_call

151個のツールを登録してクライアントのツール一覧を圧迫する代わりに、このサーバーにはsevDeskのOpenAPIドキュメントから生成された検索可能なカタログが付属します。必要な機能を検索し、シグネチャを確認して呼び出してください。すべてのエンドポイントを利用できます。

よくあるワークフロー

ツールを組み合わせて、日常的な記帳業務をそれぞれ1つのプロンプトで実行できます。

• 月次決算： 「6月の月次チェックを実施してください。未処理の下書き、領収書のない銀行支払い、支払いのない証憑、VATの指摘事項、合計の不一致を確認してください。」
• 入金の督促： 「誰からの入金が未済ですか？支払期限超過日数ごとに請求書を表示し、送信済みとして記録されていないものを教えてください。」
• 領収書の管理： 「領収書フォルダーとsevDeskを照合して、どちらかにしかないものを一覧表示してください。」（SEVDESK_RECEIPT_DIRSが必要です）
• 継続的な経費： 「表示されなくなったサブスクリプションと、記帳に一貫性のない仕入先を教えてください。」
• VAT申告の前に： 「四半期のVAT監査と§13bレポートを実行し、税理士が把握しておくべき内容を要約してください。」
• その他の操作： 「sevDesk APIを呼び出してください：…」 — 受注、クレジットノート、エクスポート、部品、その他すべてのエンドポイントをカタログから利用できます。

エージェントスキル（任意）

このパッケージにはエージェントスキルが含まれており、月次締めの順序、領収書の振り分け、§13b の調査、監査指摘の解釈といったワークフローを明記しています。これにより、エージェントはセッションごとに知識を再発見するのではなく、必要に応じてノウハウを読み込めます。Claude Code の場合は、プロジェクトの隣にコピーしてください。

cp -r node_modules/sevdesk-mcp/skills/sevdesk-bookkeeping .claude/skills/

（または、このリポジトリをクローンしてコピーしてください）。スキルに対応していないクライアントでも、失われるものはありません。サーバー独自の instructions とツールの説明に、必要な情報が含まれています。

設定

変数	デフォルト	用途
SEVDESK_API_TOKEN	(必須)	sevDesk API トークン
SEVDESK_READ_ONLY	false	ブール値（1/true/yes/on または 0/false/no/off。それ以外の値では起動時に失敗します）。書き込みツールを非表示にします。sevdesk_call は引き続き一覧に表示されますが、呼び出し時に変更を伴う操作を拒否します
SEVDESK_DRY_RUN	false	ブール値。受け付ける値は同じです。書き込み時に送信される内容を表示しますが、実際には送信しません
SEVDESK_RECEIPT_DIRS	(未設定 — ファイルツールは無効)	領収書ファイルツールによる読み書きを許可する絶対パスのディレクトリの許可リスト。プラットフォームのパス区切り文字（macOS/Linux では :、Windows では ;）で区切ります。シンボリックリンクは解決されるため、許可リスト外を指すリンクは拒否されます
SEVDESK_BASE_URL	https://my.sevdesk.de/api/v1	API ホストを上書きします。トークンはヘッダーとして送信されるため、https:// が必須です。平文の http:// は localhost、127.0.0.1、[::1] に限り使用できます
SEVDESK_TIMEOUT_MS	30000	リクエストごとのタイムアウト（0 より大きい整数）
SEVDESK_MAX_RETRIES	3	0 以上の整数。0 はリトライしないことを意味します。ジッター付きバックオフと上限を設けた Retry-After でリトライします。429 は必ずリトライされます（スロットリングされた呼び出しは実行されていません）。5xx またはネットワーク障害の場合は、読み取りに限りリトライされます。曖昧な失敗時に書き込みが再実行されることはないため、タイムアウトによって下書きが重複作成されることはありません
SEVDESK_RATE_LIMIT	4	クライアント側のリクエスト間隔制御（トークンバケット方式、毎秒のリクエスト数）。監査の一括呼び出しが集中して sevDesk のスロットリングと衝突するのを防ぎます。0 で間隔制御を無効にします
SEVDESK_DEBUG	false	ブール値。受け付ける値は同じです。METHOD /path -> status を stderr に記録します。クエリ文字列、本文、トークンは記録しません

これらの値は、MCP クライアントの env ブロックに設定してください。これがサポートされている方法であり、クライアントが管理します。クライアント外で実行する場合（クローンしたリポジトリからの npm run dev、node dist/index.js）、.env.example をパッケージのルートに .env としてコピーすると、サーバーは起動時にそれを読み込みます。このファイルは作業ディレクトリではなく、常にパッケージのルートから読み込まれます。また、実際の環境変数が常に優先されるため、クライアントの env ブロックが古い .env に上書きされることはありません。.env は gitignore に登録されています。

脅威モデル、保証、脆弱性の報告については、SECURITY.md に記載されています。

プライバシーポリシー

すべての処理はローカルで実行されます。トークンと会計データは MCP クライアントと sevDesk API の間でのみやり取りされ、保存、テレメトリー、第三者への共有はありません。ポリシー全文：PRIVACY.md。

書き込みの安全性

読み取り専用モードは3重に適用されます。書き込みツールはツール一覧から非表示になり、ディスパッチャーが書き込みツールの実行を拒否し、HTTP クライアントもすべての変更リクエストを個別に拒否します。sevdesk_call は、状態を変更する GET（sendByWithRender、真となる enshrine* フラグ、preventSendBy の無効化）を書き込みとして扱います。書き込みが有効な場合：

• すべての書き込みツールは、呼び出しごとの dryRun を受け付け、グローバルな SEVDESK_DRY_RUN に従います。
• sevdesk_create_voucher と sevdesk_create_invoice は、デフォルトで下書きを作成します。何も自動で記帳または送信されません。
• sevdesk_set_tax_rule と sevdesk_mark_invoice_sent は、確定済みの書類に対する操作を拒否し、書類を再読み込みして変更内容を検証します。
• メール送信ツールは意図的に用意していません。また、sevdesk_get_invoice_pdf が既存のファイルを上書きすることはありません。
• 記帳済みおよび支払済みの伝票は、API による再記帳の対象外です。 sevDesk API が更新できるのは下書きのみです。また、外貨建ての支払済み伝票をリセットすると、今日の為替レートでユーロ金額が再計算され、過去の金額が気付かれないまま変更されます。記帳済みの伝票は、元の金額を領収書と照合して確認できる sevDesk の UI で修正してください。

税務モデル

sevdesk-Update 2.0 では、sevDesk は taxRule を通じて VAT を扱います。これは収益用と費用用のルールセットに分かれています。古い書類には、非推奨の taxType 文字列が引き続き含まれています。サーバーは両方の世代に対応しています。

費用ルール（仕入伝票、creditDebit: "C"）：

taxRule	意味	税率	旧 taxType
8	EU域内取得	0 / 7 / 19 %	—
9	仕入税額控除の対象となる費用	0 / 7 / 19 %	default
10	仕入税額控除の対象とならない費用	0 %	ss
12	§13b Abs. 2 に基づくリバースチャージ、仕入税額控除あり	0 %	—
13	§13b に基づくリバースチャージ、仕入税額控除なし	0 %	—
14	§13b Abs. 1 に基づくリバースチャージ、EU	0 %	—
16	課税対象外（支出）	0 %	—

収益ルール（売上書類、creditDebit: "D"）：

taxRule	意味	税率	旧 taxType
1	VAT 課税対象の売上	0 / 7 / 19 %	default
2	輸出	0 %	—
3	EU域内供給	0 / 7 / 19 %	eu
4	UStG §4 に基づく非課税売上	0 %	—
5	§13b に基づくリバースチャージ（欄60）	0 %	—
11	UStG §19 に基づき税を徴収しない売上	0 %	ss
17	国内で課税されない役務	0 %	noteu
22	課税対象外（収入）	0 %	—

（ルール18～21（One Stop Shop および §18b）は請求書では使用できますが、伝票では受け付けられません。使用されている場合は監査で警告されます。）

よくある誤った記帳例は、海外に拠点を置く仕入先のサブスクリプションを、税率0％の明細を含む一般的な国内費用（taxRule 9）として記帳することです。一見問題はなさそうです。仕入税額控除が可能な場合、リバースチャージによる税額は差し引きゼロになるためです。しかし、これでは §13b の課税標準額が VAT 申告から気付かれないまま除外されます。正しい記帳は taxRule 12（状況によっては13または14）です。CSV エクスポートには税率しか含まれず、ルールは含まれないため、この違いを確認できません。sevdesk_audit_vat を使えば検出できます。

開発

npm run dev        # run from source
npm test           # unit tests
npm run typecheck  # tsc --noEmit
npm run build:catalog  # regenerate the operation catalogue from openapi/sevdesk-openapi.yaml

CONTRIBUTING.md を参照してください。

ロードマップ

• 実際のアカウント（簿記システム2.0）でのライブ検証
• 連絡先の国の検出、勘定科目ガイダンスのチェック、銀行照合
• ガード付き請求書ワークフロー（下書きのみの作成、PDF エクスポート、送信済みとしてマーク）
• リクエストごとのトークンを使用した Streamable HTTP トランスポート経由のリモートホスティング — サーバーの組み立てはすでにトランスポートに依存しません（src/server.ts）
• OpenAPI 仕様から生成するコンパイル時のエンドポイント型
• sevDesk サンドボックスに対する統合テスト
• 年次 VAT 申告向けのエクスポートヘルパー（Kz 46 / 47）

ライセンス

MIT