Tool-Plaid

You deploy and run a Model Context Protocol (MCP) server that exposes two tools for interacting with Plaid’s financial data: syncing transactions and retrieving account balances. This server lets you integrate Plaid capabilities into your MCP client workflows, while handling token encryption, storage, and caching securely and efficiently.

How to use

You interact with the Plaid MCP server through an MCP client by calling the exposed tools. Use the following workflows to accomplish common tasks:

• Sync transactions: request incremental updates for a Plaid item and receive added, modified, and removed transactions along with a cursor for subsequent calls.

• Get balances: fetch current balances for one or more Plaid accounts, with optional caching to improve performance on repeated requests.

How to install

Prerequisites you need before starting:

• Python 3.8+ is required
• Git is installed on your system
• A compatible MCP client can reach the server (STDIO or HTTP)

Development installation steps you can run locally to start experimenting:

# Clone the repository you are working with
git clone https://github.com/reilly3000/tool-plaid.git
cd tool-plaid

# Install in development mode
pip install -e .

# Or with uv (recommended for development)
uv pip install -e .

Production installation steps to deploy a ready-to-run MCP server:

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

Running the server in development (STDIO) mode uses the following commands you can execute directly from your shell:

# Set necessary environment variables as shown below
export PLAID_ENV=sandbox
export PLAID_CLIENT_ID=<your_client_id>
export PLAID_SECRET=<your_secret>
export STORAGE_MODE=file

# Start the server using uv (development)
uv run plaid-tool

# Or run directly with Python
python -m tool_plaid

Configuration and security

Key configuration and security considerations you should set before running the server in production or sharing it with a client include environment-based credentials, storage settings, and encryption keys.

# Example environment variables you may set
export PLAID_ENV=sandbox
export PLAID_CLIENT_ID=your_client_id
export PLAID_SECRET=your_secret
export ENCRYPTION_KEY=your_32_byte_key_here
export STORAGE_MODE=file
export MCP_TRANSPORT=streamable-http
export MCP_PORT=8000

Notes and tips

• If you prefer HTTP-based access, you can run the server in production mode with a streamable HTTP transport, but ensure you provide a valid endpoint to reach the server. The HTTP URL will be used by the MCP client to communicate with the server.

• For quick local testing, STDIO mode is often simplest: start the server with a direct Python invocation or with the UV wrapper to see immediate results in your development environment.

Tools exposed by the server

This MCP server provides two tools you can invoke through your MCP client:

• sync_transactions: Retrieve and sync Plaid transactions with cursor-based incremental updates
• get_balance: Retrieve account balances with caching and optional refresh

Available tools

sync_transactions

Synchronize Plaid transactions with incremental updates using a cursor, returning added, modified, removed, and next_cursor information.

get_balance

Fetch account balances with optional filtering by account IDs and an optional forced refresh to bypass cache.