How do I use Tool-Plaid?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Tool-Plaid sync my checking account transactions from the last 30 days" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Tool-Plaid: MCP Server for Plaid

MCP (Model Context Protocol) server tool that exposes two tools for interacting with Plaid's financial data API:

sync_transactions - Retrieve and sync transaction data
get_balance - Get account balances

Installation

Development Installation

# Clone the repository git clone https://github.com/reilly3000/tool-plaid.git cd tool-plaid # Install in development mode pip install -e . # Or with uv (recommended) uv pip install -e .

Production Installation

pip install tool-plaid # or with uv uv pip install tool-plaid

Configuration

Environment Variables

Create a .env.agent file in the project root (ignored by git) or set environment variables:

# Plaid Configuration PLAID_ENV=sandbox|production PLAID_CLIENT_ID=<your_client_id> PLAID_SECRET=<your_secret> # Security ENCRYPTION_KEY=<your_32_byte_encryption_key> # Storage STORAGE_MODE=file|postgres DATABASE_URL=postgresql://user:pass@host:port/dbname # required if STORAGE_MODE=postgres # MCP Server MCP_TRANSPORT=stdio|streamable-http MCP_PORT=8000 # Caching (optional) BALANCE_CACHE_TTL=300 # seconds, default: 300 (5 minutes)

Example .env File

# Sandbox Environment PLAID_ENV=sandbox PLAID_CLIENT_ID=62eacf714206f30013d6e722 PLAID_SECRET=6f85aa5808d484246313470945c515 # Generate a random 32-byte key ENCRYPTION_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))") # Start with file storage STORAGE_MODE=file

Usage

Running the Server

Local Development (STDIO)

# Set environment export PLAID_ENV=sandbox export PLAID_CLIENT_ID=<your_client_id> export PLAID_SECRET=<your_secret> export STORAGE_MODE=file # Run with uv uv run plaid-tool # Or directly python -m tool_plaid

Production (Streamable HTTP)

export PLAID_ENV=production export DATABASE_URL=postgresql://... export STORAGE_MODE=postgres export MCP_TRANSPORT=streamable-http # Run HTTP server plaid-tool

Configuration with Claude Desktop

Add this to your MCP configuration file (e.g., claude_desktop_config.json):

{ "mcpServers": { "plaid": { "command": "plaid-tool", "env": { "PLAID_ENV": "sandbox" } } } }

Tools

sync_transactions

Sync transactions from Plaid using cursor-based incremental updates.

Parameters:

item_id (required): Plaid item identifier
force_refresh (optional, default=False): Trigger Plaid refresh
days_requested (optional, default=90, range 1-730): Days of history

Returns:

{ "added": [ { "transaction_id": "string", "account_id": "string", "amount": 100.50, "date": "2025-01-15", "merchant_name": "Merchant Name", "category": "Food and Drink", "pending": false } ], "modified": [...], "removed": ["transaction_id_1", "transaction_id_2"], "next_cursor": "cursor_string", "has_more": false, "item_status": "HISTORICAL_UPDATE_COMPLETE", "summary": "Added 10, modified 2, removed 1 transactions" }

get_balance

Get account balances with intelligent caching.

Parameters:

item_id (required): Plaid item identifier
account_ids (optional, default=None): Filter specific accounts
force_refresh (optional, default=False): Bypass cache

Returns:

{ "balances": [ { "account_id": "string", "name": "Plaid Checking", "mask": "0000", "type": "depository", "available": 1000.00, "current": 1250.00, "iso_currency_code": "USD" } ], "cached": true, "timestamp": "2025-01-15T10:30:00Z" }

Architecture

Storage Modes

File Storage (Development)

JSONL files for transactions
Simple key-value cursor tracking
Text-based balance snapshots
Directory: data/items/{item_id}/

PostgreSQL (Production)

Async PostgreSQL with asyncpgres
Tables: access_tokens, transactions, balances, cursors
Connection pooling
Migrations via alembic

Security

AES-256 encryption for access tokens at rest
Encryption key from environment variable
No logging of sensitive data (tokens, raw responses)
Audit logging without sensitive data

Development

Running Tests

# Unit tests pytest tests/ -v # With coverage pytest --cov=tool_plaid --cov-report=html

End-to-End Testing (Sandbox)

Open tests/plaid_link_test.html in a browser
Link a test bank using credentials: user_good / pass_good
Copy the public token and run:

python tests/test_e2e.py <PUBLIC_TOKEN>

Note: Public tokens expire after ~30 minutes.

Quick Verification

# Check config loads python -c "from tool_plaid.config import Config; c = Config.load(); print(c.PLAID_CLIENT_ID)" # Test encryption python -c "from tool_plaid.utils.encryption import Encryptor; from tool_plaid.config import Config; e = Encryptor(Config.load().ENCRYPTION_KEY); print(e.decrypt(e.encrypt('test')))"

Code Quality

# Format code black tool_plaid # Lint ruff check tool_plaid # Type check mypy tool_plaid

License

MIT

Support

For issues and questions, please open an issue on GitHub.

Tool-Plaid