OpenVerein

登録団体（e.V.）向けのオープンソース団体管理システムです。会員、グループ、会費と請求書、SEPA口座振替、会計、予定、メール、書類、会員ポータルを管理できます。すべてをセルフホストでき、あらゆるレコードをエクスポートでき、すべての操作をREST APIから実行できます。

ライセンス：AGPL-3.0。ステータス：初期開発段階で、段階的に開発しています（openspec/ を参照）。

OpenVereinを選ぶ理由

• データはあなたのもとに残ります。 セルフホスト可能で、完全なエクスポートに対応し、サブスクリプションの罠もありません。
• ドイツの団体法に対応しています。 EÜR、GoBD、SEPA、XRechnung、BMFの様式に沿った寄付金受領証明書、DATEVエクスポートに対応しています。
• すべてAPIで操作できます。 ユーザーインターフェースは公開 /api/v1 のみを利用し、OpenAPIドキュメント、Webhook、AIエージェント向けのMCP連携を備えています。
• 自由に利用できます。 AGPL-3.0のもとでオープンに開発されており、貢献を歓迎します。

内容

• OpenVereinでできること
• デモを試す
• ローカルで起動
• 団体向け
• Claude Code に接続
• サーバーで運用する
• テスト
• プロジェクトの構成
• 参加する

OpenVereinでできること

領域	主な機能
会員	日付付きのグループ所属、支払者と家族割引を設定できる世帯、独自フィールド、重複データ、保存済みビュー、一括操作、年齢に応じたグループ変更、州スポーツ連盟向けの会員数調査、表彰記録とお祝いメール、連絡記録、データ品質に関する注意、活動時間、会員証明書、PDFおよびvCard形式のリスト
会計	適用開始日と年齢別料金を設定できる会費、会費処理のたびに必須となる事前プレビューと任意の自動月次プレビュー、請求書に変換できる見積書、定型文と税抜価格または税込価格を設定できる請求書、督促状を含む督促管理、SEPA口座振替（摘要テンプレート）と振込、照合機能付きのCAMTインポート、送受信対応のXRechnung（ZUGFeRD/UBL/CII）、商品カタログ、両面印刷用の一括PDF
帳簿	均衡した追記専用仕訳帳（GoBD準拠の記録固定、取消仕訳）に基づく収支計算書（EÜR）、証憑と現金出納帳、口座の入出金の集計と記帳、独自の税率、DATEVエクスポート、PDF形式の現金出納報告書、予定額と実績額の比較、ボランティア活動手当、BMFの書式に準拠した寄付金および寄付証明書（金銭・物品の寄付）のメールまたは郵送
クラブ活動	出欠回答、キャンセル待ちリスト、助成金申請用の出席者リストを備えた予定、ICSフィードとインポート、公開カレンダーウィジェット、テンプレートと送信記録を備えたメール、フォルダー単位の権限を設定できる文書、備品と貸し出し、アンケート、タスク、議事録付きの会員総会と理事会
ポータル	会員向けセルフサービス：情報の変更、GiroCode付き請求書、文書、アンケート、経費精算、支払者に代わる世帯の手続き、クラブやグループごとに機能の有効・無効を切り替え
プラットフォーム	部門との関連付けとフィールド制限を設定できるロール、財務機能向けTOTP、APIトークンとOpenAPI、署名付きWebhook、バックグラウンドジョブ、完全エクスポート、GDPR対応ツール、インストール、バックアップ、復元、更新用のovctl

デモを試す

インストール不要： 公開デモは https://klub2.ki-klub-werder.de で利用できます。定期的にリセットされ、実際のメールは送信されません。また、架空のデータのみが含まれています。

ローカル環境でデモクラブを読み込むには、次のようにします。

npm run seed:demo    # lädt den „SV Lindenhof 1921 e.V.“ mit 150 erfundenen Mitgliedern in eine leere Instanz
npm run dev

[email protected] / verein-demo-2026でログインしてください。npm run seed:demo -- --resetはデモインスタンスを空にして再読み込みします。実際のクラブが登録されているインスタンスには影響しません。

DEMO_MODE=trueを設定すると、サーバーがデモを読み込み、DEMO_RESET_HOURS（既定値は24）ごとにリセットします。このモードでは、実際のメールは送信されず、デモバナーが表示され、すべてのPDFに透かしが入ります。また、公開デモを誰でも利用できるよう、アカウント、ロール、APIキー、アップロード、インポートがロックされます。訪問者は次回リセットまで、クラブの設定、テキスト、会員情報を編集できます。会員ポータルでは、ログインコードをメールで送信せず、画面に表示します。実際のクラブが登録されているインスタンスでは、DEMO_MODE=trueを指定したサーバーは起動しません。

DEMO_MODE=true docker compose --profile app up --build

ローカルで起動する

前提条件：Node 24、Docker。

cp .env.example .env
npm install
npm run dev

npm run devを実行すると、DockerでPostgresとMailpitが起動し、マイグレーションが適用され、APIがhttp://localhost:3300で、Webアプリがhttp://localhost:5173で起動します。初回アクセス時にクラブを設定します。アプリから送信されるメールは、Mailpitのhttp://localhost:18025で確認できます。

APIリファレンス：http://localhost:3300/api/docs（OpenAPIドキュメントは`/api/v1/openapi.json`）。

アプリ全体をDockerで起動する

docker compose --profile app up --build

http://localhost:3300を開いてください。

Verein向け

• 会計担当者向けハンドブック：会費の徴収から税務相談まで、クラブの1年間を解説します。
• 理事会・管理担当者向けハンドブック：会員、入会、日程、メール、ポータル、データ保護について解説します。
• 手順書（テンプレート）：記入して使える、GoBD準拠の手順書テンプレートです。

Claude Code に接続する

このプラグインは、<club>/mcp のリモートMCPサーバーを介して Claude Code をクラブに接続します。エージェントに見えるもの、実行できることは、クラブ管理画面または会員ポータルであなたに見えるもの、実行できることと同じで、それ以上ではありません。

1. Claude Code にプラグインをインストールします。

   /plugin marketplace add KI-Klub-Werder-e-V/openverein
   /plugin install openverein@openverein
   

   Claude Code 2.1.275 以降では、次のように1つの手順でインストールすることもできます：/plugin install openverein --marketplace KI-Klub-Werder-e-V/openverein。

2. 尋ねられたら、クラブのアドレスを入力します。例：https://verein.example.org。公開デモを使う場合は、https://klub2.ki-klub-werder.de と入力します。後から /plugin configure openverein@openverein でアドレスを変更できます。その後、再度ログインしてください。シェルでは、インストール時にアドレスを直接指定します：claude plugin install openverein@openverein --config club_url=https://verein.example.org。

3. ログインします：/mcp を実行し、openverein を選択して認証します。ブラウザーでは次のようにします。

   • 会員はポータルでメールコードを使ってログインします
   • クラブ管理画面には通常のログイン情報と二要素認証でログインします

   ログインする前に、ブラウザーにクラブのアドレスが表示されていることを確認してください。次に「読み取りのみ」または「読み取りと書き込み」を選択し、アクセスを許可します。トークンがファイルに保存されることはありません。

4. たとえば、「未払いの請求書はありますか？」や「火曜日のトレーニングに申し込んだのは誰ですか？」と尋ねます。

エージェントの呼び出し履歴は 設定 → エージェント（または ポータル → エージェント）で確認でき、ここでアクセスを取り消すこともできます。スクリプトとコマンドラインツール ov は OAuth の代わりに、同じページから取得したトークンを使います。claude.ai と ChatGPT は、同じアドレス <club>/mcp をカスタムコネクターとして接続します。

サーバーで運用する

./ovctl install は Docker Compose を使って Caddy（HTTPS）、アプリ、Postgres をセットアップします。./ovctl backup、restore、update、doctor で、すべてを正常に稼働させます。詳細は docs/operations.md を参照してください。

テスト

npm run typecheck && npm run lint
npm test            # Unit- und Integrationstests (braucht den Postgres-Container)
npm run test:e2e    # End-to-End-Tests mit Playwright
npm run validate:xrechnung  # Beispiel-E-Rechnungen durch den offiziellen KoSIT-Validator (braucht Java 17+ oder Docker)

プロジェクトの構成

• openspec/specs/ は動作に関する正式な記述で、機能ごとに仕様があります。それぞれの機能は openspec/changes/ にある OpenSpec の変更として作成され、マージ後にアーカイブされます。
• src/server/ は Fastify API、src/web/ は React アプリ、src/shared/ は両方で共有するスキーマ、migrations/ は前方にのみ適用される SQL マイグレーションです。
• docs/adr/ はアーキテクチャに関する決定、docs/decisions.md は小規模な決定を記録します。
• PRODUCT.md と DESIGN.md では、プロダクトとデザインシステムについて説明しています。
• android/、ios/、capacitor.config.ts、codemagic.yaml は、Web ビルドをパッケージ化するモバイルアプリです。docs/mobile.md を参照してください。

参加する

不具合報告、機能のリクエスト、ドキュメント、コードなど、貢献を歓迎します。

• CONTRIBUTING.md：セットアップ、OpenSpec を使った作業方法、ルール、PR チェックリスト。
• SECURITY.md：セキュリティ上の脆弱性は、公開 Issue としてではなく、機密扱いで報告してください。
• CODE_OF_CONDUCT.md：行動規範。
• Issues：不具合を報告したり、機能を提案したりできます。