filevine-mcp

Filevine MCP — Claude 連携

Oktopeak が開発 — 法律事務所向けの AI トランスフォーメーションと自動化

法律・医療関連企業のデジタルトランスフォーメーション。 AI 連携、ワークフロー自動化、そして貴事務所が完全に所有できるカスタムソフトウェア（このコネクターを含む）を構築します。→ 30 分の相談を予約

Claude を Filevine の業務管理プラットフォームに接続するオープンソースの MCP（Model Context Protocol）サーバーです。自動レート制限と監査ログを備え、Claude から案件、連絡先、ドキュメント、メモ、タスク、カスタム PI データにアクセスできます。

対応エンドポイント： Filevine v2 REST API をカバーする 15 個のツール。

ヒント

開発者でなくても大丈夫です。

以下の README は、JSON 設定ファイルの編集に慣れている方を想定しています。ご自身やチームが該当しない場合は、法律事務所向けに導入を代行します。範囲を限定した認証情報、監査ログの設定、カスタムワークフロー 1 件、トレーニングが含まれます。

→ 事務所全体で利用しますか？Firm Plan：月額 300 ドル。 お客様のクラウド環境にセットアップし、弁護士がそれぞれのログイン情報でサインインできます。監査ログは 1 つ、毎月お客様向けの自動化を 1 件構築します。セットアップ料金は不要で、いつでも解約できます。→ oktopeak.com/firm-plan/、または30 分の相談を予約

ジャンプ先： セットアップ · 利用可能なツール · コンプライアンスとセキュリティ · 導入を依頼しますか？ · その他のコネクター

---

セットアップ

1. 前提条件

• Node.js 18+
• API アクセスが有効な Filevine アカウント
• 事務所の Filevine 設定で取得した Client ID、Client Secret、Personal Access Token（PAT）
• Claude Code、MCP クライアント、または互換性のあるアプリケーション

2. Filevine 認証情報を取得する

1. Personal Access Token（PAT）

   • Filevine Settings → Access Tokens → Generate PAT に移動します
   • コピーして安全に保存します

2. クライアント認証情報

   • Settings → Client Secrets → Create Client ID + Client Secret に移動します
   • 有効期間は 1 年で、いつでもローテーションできます
   • 両方の値をコピーします

3. 組織 ID とユーザー ID（初回の認証呼び出し時に自動検出されます）

   • サーバーは初回実行時に /v2/users/me からこれらを検出します

3. 環境変数

.env.example を .env にコピーします：

# Filevine OAuth client credentials
FILEVINE_CLIENT_ID=<from Settings → Client Secrets>
FILEVINE_CLIENT_SECRET=<from Settings → Client Secrets>
FILEVINE_PAT=<from Settings → Access Tokens>

# API region (us or ca)
FILEVINE_REGION=us

# Token encryption key (generate new one)
# node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
ENCRYPTION_KEY=<64-character-hex-string>

4. インストールとビルド

npm install
npm run build

5. サーバーを実行する

# Start the server
npm start

# Or use MCP inspector for debugging
npm run inspect

サーバーは stdio で待ち受け、接続状態を stderr に出力します。

6. 認証する

Filevine のツールを使用する前に、authenticate ツールを呼び出してください：

Tool: authenticate
→ Exchanges PAT for access token
→ Discovers org_id and user_id
→ Stores encrypted tokens in ~/.oktopeak-filevine/tokens.enc

トークンは有効期限（TTL 3600 秒）の前に自動更新されます。保存されたトークンを消去するには、logout を呼び出してください。

---

ツール（合計 15 個）

認証（3 個のツール）

ツール	用途
authenticate	PAT をアクセストークンと交換し、組織 ID とユーザー ID をキャッシュします
auth-status	認証状態とトークンの有効期限を確認します
logout	保存されたトークンを消去します

案件 — プロジェクト（2 個のツール）

ツール	用途
list-cases	案件（進行中、クローズ済み、保留中）を一覧表示します。名前または番号で検索できます
get-case	ID を指定して案件の詳細をすべて取得します

連絡先（3 個のツール）

ツール	用途
search-contacts	すべての案件を対象に、名前、メールアドレス、電話番号で連絡先を検索します
get-contact	ID を指定して連絡先の詳細を取得します
list-case-contacts	特定の案件に登録されている連絡先をすべて一覧表示します

メモ（2 個のツール）

ツール	用途
list-notes	案件のメモを一覧表示します。general、phone_call、internal のタイプに対応しています
create-note	メモを作成します（例：AI による要約、調査結果、フォローアップ）

Documents（1 個のツール）

ツール	用途
list-documents	ケース文書のメタデータ（名前、種類、サイズ、URL、日付）を一覧表示します

注： 返されるのは文書のメタデータのみで、バイナリコンテンツは含まれません。文書の内容が必要な場合は、返されたURLを使用して取得してください。

Tasks（2 個のツール）

ツール	用途
list-tasks	ステータス（未完了、完了、期限超過）別にケースのタスクを一覧表示します
create-task	タイトル、説明、担当者、期限を指定して新しいタスクを作成します

既知の問題： 2025年8月時点では、Filevine APIによってtargetDateフィールドが無視される場合があります。回避策：UIからタスクを設定してください。

Custom Data — Collections（2 個のツール）

ツール	用途
discover-schema	法律事務所のカスタムセクション（医療記録、先取特権、和解など）をマッピングします
get-collection	検出したセレクターを使用してカスタムコレクションデータを取得します

コレクションが重要な理由： 標準化されたケースフィールドとは異なり、PIワークフローでは各法律事務所が独自の「Collection sections」を構築しています。discover-schemaツールで、法律事務所の構造を確認できます。

ワークフローの例：

1. discover-schemaを呼び出す → 利用可能なセクション（例：「MedicalRecords」、「Liens」）を確認します
2. 検出結果のセレクターを使用する → get-collectionでPI固有のデータを取得します

---

レート制限とパフォーマンス

Filevineのレート制限：

エンドポイント	上限
標準	320 req/endpoint/min
Billing	250 req/endpoint/min
Reports/Vitals	5 req/endpoint/min
VineSign	10 req/user/month

実装：

• 300 req/minのトークンバケット（保守的な設定）
• 429 Too Many Requestsの場合、指数バックオフ（1s → 2s → 4s → ... → 最大30s）
• レート制限に達する前に自動的に待機

---

APIの詳細

リクエストの流れ

1. トークン交換（最初のauthenticate呼び出し時）

   POST https://identity.filevine.com/connect/token
   client_id, client_secret, grant_type=personal_access_token, token=PAT
   → access_token (3600s), refresh_token, scopes
   

2. 組織／ユーザーの検出

   GET /v2/users/me
   Authorization: Bearer {access_token}
   → {id: user_id, org_id: org_id}
   

3. すべてのAPIリクエスト（必須ヘッダー3個）

   Authorization: Bearer {access_token}
   x-fv-orgid: {org_id}
   x-fv-userid: {user_id}
   

ベースURL

• US： https://api.filevine.io
• CA： https://api.filevine.ca

FILEVINE_REGION環境変数で設定します。

認証ヘッダー

他の法律関連APIとの最大の違いは、Authorizationだけでなく、すべてのリクエストに3個のヘッダーが必要なことです。Filevineはx-fv-orgidとx-fv-useridを使用して、正しい組織とユーザーのコンテキストにクエリを適用します。

---

アーキテクチャ

src/
├── index.ts                      # Server entry point
├── filevine-client.ts            # API client with 3-header middleware
├── auth/
│   ├── authTools.ts              # authenticate, auth-status, logout
│   ├── oauth.ts                  # PAT token exchange + org/user discovery
│   └── token-store.ts            # AES-256-GCM encrypted token storage
├── tools/
│   ├── cases.ts                  # list-cases, get-case
│   ├── contacts.ts               # search-contacts, get-contact, list-case-contacts
│   ├── notes.ts                  # list-notes, create-note
│   ├── documents.ts              # list-documents
│   ├── tasks.ts                  # list-tasks, create-task
│   └── collections.ts            # discover-schema, get-collection
├── resources/
│   ├── auth-status.ts            # Auth status resource (filevine://auth/status)
│   └── compliance.ts             # Compliance notice
├── audit/
│   └── logger.ts                 # Audit logging (JSON-lines)
└── utils/
    └── rate-limiter.ts           # Token bucket + 429 backoff

トークンの保存

トークンはAES-256-GCMで暗号化され、ローカルに保存されます。

• 場所： ~/.oktopeak-filevine/tokens.enc
• 暗号化： ランダムなIVと認証タグを使用したAES-256-GCM
• キー： .envのENCRYPTION_KEY（64文字の16進数）

監査ログ

すべてのツール呼び出しは~/.oktopeak-filevine/audit.logに記録されます。

• タイムスタンプ、ツール名、引数（シークレットはマスキング）
• 結果（成功／エラー）、ユーザーID、ケースID、結果件数
• ABA Opinion 512への準拠を示す文書作成に対応

---

エラー処理

よくあるエラー

エラー	原因	修正方法
ENCRYPTION_KEY is not set	環境変数が未設定	キーを生成します：node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
PAT exchange failed (401)	認証情報が無効	Filevine SettingsでClient ID、Secret、PATを確認してください
Failed to discover user info	トークンに必要なスコープがない	FilevineでPATとClient Credentialsを再生成してください
429 Too Many Requests	レート制限に到達	サーバーが自動的にバックオフします。負荷時には通常の動作です
Unknown collection selector	セレクターが見つからない	discover-schemaを実行して、利用可能なセレクターを確認してください

---

開発

TypeScript

• Strictモードを有効化
• ES2022ターゲット、Node16モジュール
• npm run build → build/ディレクトリ

依存関係

• @modelcontextprotocol/sdk — MCPプロトコル
• dotenv — 環境変数の読み込み
• zod — ツールパラメーターのスキーマ検証
• crypto、fs、http — Node組み込みモジュール

デバッグ

npm run inspect

http://localhost:3000 でMCPインスペクターを開きます。ツールのテスト、パラメーターの確認、応答の検証ができます。

テスト

npm run build
npm start
# In another terminal:
npm run inspect

---

リソース

Official Filevine

• API ドキュメント： developer.filevine.io
• サポート： support.filevine.com/hc/en-us
• サンプル： github.com/Filevine/filevine-api-examples（C#、JS、Python）
• レート制限： support.filevine.com/hc/en-us/articles/30948396130203

参考実装

• Treillage（Python）： github.com/W1ndst0rm/Treillage — レートリミッターとトークン更新の参考実装

---

コンプライアンスとセキュリティ

• データの取り扱い： Filevine のデータはすべてオンデマンドで取得し、ローカルにはキャッシュしません
• トークンの保存： ディスク上で AES-256-GCM により暗号化されます。復号には ENCRYPTION_KEY が必要です
• 監査ログ： すべてのツール呼び出しを、シークレットをマスキングして記録します
• レート制限： 1 分あたり 300 リクエストのローリングウィンドウと 429 応答時のバックオフにより、アカウントを保護します
• 書き込みアクセス： データを変更するのは create-note と create-task のみです
• トークンの更新： 有効期限の 5 分前に自動更新します（TTL は 3600 秒）

コンプライアンスに関する通知の全文は、src/resources/compliance.ts をご覧ください。

---

ライセンス

MIT — Oktopeak

---

コネクター以上のサポートが必要ですか？

オープンソースのコネクターは Filevine のデータを読み取り、Claude がそのデータを使えるようにします。多くの法律事務所が最終的に求める機能のうち、対応できるのは約 20% です。

ご要望の範囲に応じて、2 つの方法で支援します。

→ 事務所全体で利用しますか？ Firm Plan：月額 300 ドル。 お客様のクラウド環境にセットアップし、各弁護士が各自のログインでサインインできます。監査ログは 1 つにまとまり、毎月お客様向けの自動化を 1 つ構築します。セットアップ料金は不要で、いつでも解約できます。→ oktopeak.com/firm-plan/

→ Filevine インテグレーション：カスタムレポート、プロジェクトスキーマの構築、文書およびインテークの自動化、Filevine を取り巻く本番用ソフトウェアレイヤーに対応します。 → oktopeak.com/services/filevine-integration/

FAQ を含む、このコネクターのわかりやすい概要をご覧になりますか？ → oktopeak.com/filevine-mcp/

まずは相談しますか？ → 30 分のスコープ相談を予約

---

Oktopeak のその他のコネクター

他の法律事務所向け業務管理プラットフォームにも、同様のコネクターを提供しています。それぞれの概要ページは oktopeak.com にあります。

• Clio MCP：Clio の法律事務所向け業務管理。ソース：github.com/oktopeak/clio-mcp。npm：@oktopeak/clio-mcp
• MyCase MCP：MyCase の法律事務所向け業務管理。ソース：github.com/oktopeak/mycase-mcp。npm：@oktopeak/mycase-mcp
• Lawmatics MCP：法律事務所向け CRM およびインテークの Lawmatics。ソース：github.com/oktopeak/lawmatics-mcp。npm：@oktopeak/lawmatics-mcp
• IntakeQ / PracticeQ MCP：IntakeQ/PracticeQ（医療・ヘルスケア）向けの HIPAA に配慮したコネクター。PHI の読み取り・書き込みをすべて監査ログに記録します。npm：@oktopeak/intakeq-mcp

同じアーキテクチャ、同じ監査ログ、同じ保存データの暗号化を採用しています。すべて MIT ライセンスです。

---

このプロジェクトを応援する

このコネクターは無料の MIT ライセンスで提供され、Oktopeak がメンテナンスしています。今後も変わりません。寄付は受け付けていません。時間の節約に役立った場合、実際に助けになることはこちらです。

• このリポジトリにスターを付けてください。 他の事務所に見つけてもらうための、本当に大切な方法です。
• Filevine を利用している別の事務所に紹介してください。
• 直接お役に立てた場合は、**レビューを投稿**してください。
• 事務所への導入、機能拡張、メンテナンスが必要ですか？ **商用サポート**をご利用ください。これが無料の取り組みを支えています。

私たちについて

Oktopeak — 法律事務所と医療分野のデジタルトランスフォーメーション。

私たちは、規制のある業界向けに AI ソリューションを開発する、社内の7人のプロダクトチームです。AI 統合、ワークフローの自動化、そしてお客様が完全に所有できるカスタムソフトウェアを手がけています。5つのオープンソース MCP コネクター — Clio、MyCase、Filevine、Lawmatics、IntakeQ — をメンテナンスし、適切な範囲に限定した認証情報、監査ログ、チームの実際の業務に合わせたワークフローとともに、実際の事務所に導入しています。

• 🌐 oktopeak.com
• 📅 30分の通話を予約
• ✉️ [email protected] — セキュリティに関する報告を歓迎します
• 💼 LinkedIn