io.github.oktopeak/filevine-mcp

Filevine MCP — Claude Integration

Built by Oktopeak — AI transformation & automation for law firms

Digital transformation for legal and healthcare businesses. We build AI integrations, workflow automation, and custom software your firm owns outright — including this connector. → Book a 30-min call

An open-source MCP (Model Context Protocol) server connecting Claude to Filevine practice management platform. Access cases, contacts, documents, notes, tasks, and custom PI data from Claude with automatic rate limiting and audit logging.

Supported Endpoints: 15 tools covering the Filevine v2 REST API.

[!TIP] Not a developer? You don't need to be.

The README below assumes someone comfortable editing a JSON config file. If that's not you or your team, we deploy this for law firms: scoped credentials, audit log wired in, one custom workflow, training.

→ Whole firm? The Firm Plan: $300 a month. Set up in your own cloud, every attorney signs in with their own login, one audit log, one automation built for you each month, no setup fee, cancel any time. → oktopeak.com/firm-plan/, or book a 30-min call

Jump to: Setup · Available tools · Compliance & security · Need it deployed for you? · Other connectors

Setup

1. Prerequisites

• Node.js 18+
• Filevine account with API access enabled
• Client ID, Client Secret, and Personal Access Token (PAT) from your firm's Filevine settings
• Claude Code, MCP client, or compatible application

2. Get Filevine Credentials

1. Personal Access Token (PAT)
   • Go to Filevine Settings → Access Tokens → Generate PAT
   • Copy and save securely
2. Client Credentials
   • Go to Settings → Client Secrets → Create Client ID + Client Secret
   • Valid for 1 year, can be rotated anytime
   • Copy both values
3. Organization & User IDs (auto-discovered on first auth call)
   • The server will discover these from /v2/users/me on first run

3. Environment Variables

Copy .env.example to .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. Install & Build

npm install
npm run build

5. Run the Server

# Start the server
npm start

# Or use MCP inspector for debugging
npm run inspect

The server listens on stdio and outputs connection status to stderr.

6. Authenticate

Before using any Filevine tools, call the authenticate tool:

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

Tokens auto-refresh before expiry (3600s TTL). Call logout to clear stored tokens.

Tools (15 Total)

Authentication (3 tools)

Cases — Projects (2 tools)

Contacts (3 tools)

Notes (2 tools)

Documents (1 tool)

Note: Returns document metadata only — no binary content. Use returned URLs to fetch document content if needed.

Tasks (2 tools)

Known Issue: The targetDate field may be ignored by the Filevine API as of Aug 2025. Workaround: set tasks via UI.

Custom Data — Collections (2 tools)

Why collections matter: Unlike standardized case fields, each firm builds custom "Collection sections" for PI workflows. The discover-schema tool finds your firm's structure.

Example workflow:

1. Call discover-schema → see available sections (e.g., "MedicalRecords", "Liens")
2. Use selector from discovery → get-collection to fetch PI-specific data

Rate Limiting & Performance

Filevine Rate Limits:

Implementation:

• Token bucket at 300 req/min (conservative)
• Exponential backoff on 429 Too Many Requests (1s → 2s → 4s → ... → 30s max)
• Automatic wait before rate limit breach

API Details

Request Flow

1. Token Exchange (on first authenticate call)

    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. Org/User Discovery

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

3. Every API Request (3 required headers)

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

Base URLs

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

Set via FILEVINE_REGION environment variable.

Authentication Headers

The biggest difference from other legal APIs: every request needs 3 headers, not just Authorization. Filevine uses x-fv-orgid and x-fv-userid to scope queries to the correct organization and user context.

Architecture

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

Token Storage

Tokens are encrypted with AES-256-GCM and stored locally:

• Location: ~/.oktopeak-filevine/tokens.enc
• Encryption: AES-256-GCM with random IV + auth tag
• Key: ENCRYPTION_KEY from .env (64-char hex)

Audit Logging

Every tool call is logged to ~/.oktopeak-filevine/audit.log:

• Timestamp, tool name, arguments (secrets redacted)
• Outcome (success/error), user ID, case ID, result count
• Supports ABA Opinion 512 compliance documentation

Error Handling

Common Errors

Development

TypeScript

• Strict mode enabled
• ES2022 target, Node16 modules
• npm run build → build/ directory

Dependencies

• @modelcontextprotocol/sdk — MCP protocol
• dotenv — Environment loading
• zod — Schema validation for tool parameters
• crypto, fs, http — Node builtins

Debugging

npm run inspect

Opens MCP inspector at http://localhost:3000 — test tools, check parameters, verify responses.

Testing

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

Resources

Official Filevine

• API Docs: developer.filevine.io
• Support: support.filevine.com/hc/en-us
• Examples: github.com/Filevine/filevine-api-examples (C#, JS, Python)
• Rate Limits: support.filevine.com/hc/en-us/articles/30948396130203

Reference Implementations

• Treillage (Python): github.com/W1ndst0rm/Treillage — Rate limiter + token refresh reference

Compliance & Security

• Data Handling: All Filevine data fetched on-demand — nothing cached locally
• Token Storage: AES-256-GCM encrypted on disk; decryption requires ENCRYPTION_KEY
• Audit Logging: Every tool call logged with redacted secrets
• Rate Limiting: 300 req/min rolling window + 429 backoff protects your account
• Write Access: Only create-note and create-task modify data
• Token Refresh: Auto-refresh 5 min before expiry (3600s TTL)

See src/resources/compliance.ts for full compliance notice.

License

MIT — Oktopeak

Need more than the connector?

The open-source connector reads your Filevine data and lets Claude work with it. That handles about 20% of what most firms eventually want.

We help two ways, depending on your scope:

→ Whole firm? The Firm Plan: $300 a month. Set up in your own cloud, every attorney signs in with their own login, one audit log, one automation built for you each month, no setup fee, cancel any time. → oktopeak.com/firm-plan/

→ Filevine Integration: For custom reporting, project schema work, document and intake automation, and the production software layer around Filevine. → oktopeak.com/services/filevine-integration/

Want a polished overview of this connector with FAQ? → oktopeak.com/filevine-mcp/

Want to talk first? → Book a 30-min scoping call

Other connectors by Oktopeak

We ship the same kind of connector for other practice management platforms. Each has its own overview page on oktopeak.com:

• Clio MCP: Clio practice management. Source: github.com/oktopeak/clio-mcp. npm: @oktopeak/clio-mcp
• MyCase MCP: MyCase legal practice management. Source: github.com/oktopeak/mycase-mcp. npm: @oktopeak/mycase-mcp
• Lawmatics MCP: Lawmatics legal CRM and intake. Source: github.com/oktopeak/lawmatics-mcp. npm: @oktopeak/lawmatics-mcp
• IntakeQ / PracticeQ MCP: HIPAA-aware connector for IntakeQ/PracticeQ (healthcare). Audit logging on every PHI read/write. npm: @oktopeak/intakeq-mcp

Same architecture, same audit logging, same encryption at rest. All MIT licensed.

Supporting this project

This connector is free, MIT licensed, and maintained by Oktopeak. It always will be — we don't take donations. If it saved you time, the things that actually help:

• Star this repo. It is genuinely how other firms find it.
• Tell another firm running Filevine.
• Leave a review if we helped you directly.
• Need it deployed, extended, or maintained for your firm? Commercial support — that is what funds the free work.

Who we are

Oktopeak — digital transformation for law firms and healthcare.

We're a 7-person in-house product team building AI solutions for regulated industries: AI integrations, workflow automation, and custom software our clients own outright. We maintain five open-source MCP connectors — Clio, MyCase, Filevine, Lawmatics, and IntakeQ — and deploy them inside real practices with scoped credentials, audit logs, and workflows built around how your team actually works.

• 🌐 oktopeak.com
• 📅 Book a 30-min call
• ✉️ office@oktopeak.com — security reports welcome
• 💼 LinkedIn