io.github.oktopeak/filevine-mcp
Open-source MCP server connecting Claude to Filevine practice management. Built by Oktopeak.
Ask AI about io.github.oktopeak/filevine-mcp
Powered by Claude Β· Grounded in docs
I know everything about io.github.oktopeak/filevine-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Filevine MCP β Claude Integration
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.
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
-
Personal Access Token (PAT)
- Go to Filevine Settings β Access Tokens β Generate PAT
- Copy and save securely
-
Client Credentials
- Go to Settings β Client Secrets β Create Client ID + Client Secret
- Valid for 1 year, can be rotated anytime
- Copy both values
-
Organization & User IDs (auto-discovered on first auth call)
- The server will discover these from
/v2/users/meon first run
- The server will discover these from
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)
| Tool | Purpose |
|---|---|
authenticate | Exchange PAT for access token and cache org/user IDs |
auth-status | Check authentication status and token expiry |
logout | Clear stored tokens |
Cases β Projects (2 tools)
| Tool | Purpose |
|---|---|
list-cases | List cases (active, closed, pending); search by name/number |
get-case | Get full case details by ID |
Contacts (3 tools)
| Tool | Purpose |
|---|---|
search-contacts | Search contacts by name, email, or phone across all cases |
get-contact | Get contact details by ID |
list-case-contacts | List all contacts on a specific case |
Notes (2 tools)
| Tool | Purpose |
|---|---|
list-notes | List case notes; supports general, phone_call, and internal types |
create-note | Create a note (e.g., AI summary, findings, follow-ups) |
Documents (1 tool)
| Tool | Purpose |
|---|---|
list-documents | List case documents with metadata (name, type, size, URL, dates) |
Note: Returns document metadata only β no binary content. Use returned URLs to fetch document content if needed.
Tasks (2 tools)
| Tool | Purpose |
|---|---|
list-tasks | List case tasks by status (open, completed, overdue) |
create-task | Create a new task with title, description, assignee, due date |
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)
| Tool | Purpose |
|---|---|
discover-schema | Map your firm's custom sections (medical records, liens, settlements, etc.) |
get-collection | Fetch custom collection data using discovered selectors |
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:
- Call
discover-schemaβ see available sections (e.g., "MedicalRecords", "Liens") - Use selector from discovery β
get-collectionto fetch PI-specific data
Rate Limiting & Performance
Filevine Rate Limits:
| Endpoint | Limit |
|---|---|
| Standard | 320 req/endpoint/min |
| Billing | 250 req/endpoint/min |
| Reports/Vitals | 5 req/endpoint/min |
| VineSign | 10 req/user/month |
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
-
Token Exchange (on first
authenticatecall)POST https://identity.filevine.com/connect/token client_id, client_secret, grant_type=personal_access_token, token=PAT β access_token (3600s), refresh_token, scopes -
Org/User Discovery
GET /v2/users/me Authorization: Bearer {access_token} β {id: user_id, org_id: org_id} -
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_KEYfrom.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
| Error | Cause | Fix |
|---|---|---|
ENCRYPTION_KEY is not set | Missing env var | Generate key: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" |
PAT exchange failed (401) | Invalid credentials | Verify Client ID, Secret, PAT from Filevine Settings |
Failed to discover user info | Token doesn't have required scopes | Regenerate PAT and Client Credentials in Filevine |
429 Too Many Requests | Rate limit hit | Server auto-backs off; normal behavior under load |
Unknown collection selector | Selector not found | Run discover-schema to find available selectors |
Development
TypeScript
- Strict mode enabled
- ES2022 target, Node16 modules
npm run buildβbuild/directory
Dependencies
@modelcontextprotocol/sdkβ MCP protocoldotenvβ Environment loadingzodβ Schema validation for tool parameterscrypto,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-noteandcreate-taskmodify data - Token Refresh: Auto-refresh 5 min before expiry (3600s TTL)
See src/resources/compliance.ts for full compliance notice.
License
MIT β Oktopeak
Related
- Clio MCP: github.com/oktopeak/clio-mcp β Similar connector for Clio practice management
