Plaid Transactions MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with Plaid's Transactions API. This server enables Claude to sync, search, and analyze your financial transactions securely.

Features

🛠️ Four Powerful Tools

plaid_list_accounts - List all your linked Plaid accounts
- Shows all accounts stored in keychain
- Displays friendly names (e.g., "American Express", "Citibank")
- Use this to see which accounts you can query
plaid_sync_transactions - Sync all transactions with automatic pagination
- Retrieves added, modified, and removed transactions
- Supports filtering by account and date range
- Handles cursor-based pagination automatically
- Works with multiple accounts - specify by name
- Returns data in Markdown or JSON format
plaid_get_transaction_categories - Get Plaid's transaction category taxonomy
- Shows all available categories and their hierarchy
- Useful for understanding transaction categorization
- No authentication required
plaid_search_transactions - Search and filter transactions intelligently
- Filter by merchant name, category, amount range, or date
- Supports partial matching for merchant and category searches
- Works with multiple accounts - specify by name
- Combines sync + filtering in one operation

🔐 Security Features

Stores credentials in macOS Keychain (never in files)
No credentials in code or environment files
Follows secure credential management best practices

⚡ Smart Features

Automatic pagination - Fetches all data without manual paging
Response truncation - Handles large datasets gracefully with helpful guidance
Clear error messages - Actionable error messages guide you to solutions
Dual output formats - Human-readable Markdown or machine-readable JSON

Installation

1. Install Dependencies

cd ~/plaid-transactions-mcp
pip install -r requirements.txt

2. Set Up Plaid Credentials in Keychain

You need to store three values in macOS Keychain:

# Store your Plaid Client ID
security add-generic-password -s "PLAID_CLIENT_ID" -a "plaid" -w "your_client_id_here"

# Store your Plaid Secret
security add-generic-password -s "PLAID_SECRET" -a "plaid" -w "your_secret_here"

# Store your Plaid Access Token (obtained after linking an account)
security add-generic-password -s "PLAID_ACCESS_TOKEN" -a "plaid" -w "access-sandbox-xxx"

Where to get these values:

Client ID & Secret: Get from Plaid Dashboard
Access Token: Obtained after a user completes Plaid Link flow (see below)

3. Getting an Access Token

To get transactions, you first need an access token by having a user link their bank account:

Create a Link Token using /link/token/create with transactions in the products array
User completes Plaid Link flow in your app
Exchange the public token for an access token using /item/public_token/exchange
Store the access token in Keychain

For testing, use Plaid Sandbox credentials.

4. Configure Claude Desktop

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "plaid-transactions": {
      "command": "python",
      "args": ["/Users/sfinnerty/plaid-transactions-mcp/plaid_mcp.py"]
    }
  }
}

5. Restart Claude Desktop

After updating the config, restart Claude Desktop to load the MCP server.

Usage Examples

List Your Accounts

What Plaid accounts do I have?

Claude will use plaid_list_accounts to show all your linked accounts.

Sync All Recent Transactions

Show me my recent American Express transactions

Claude will use plaid_sync_transactions with the American Express account.

Show me all transactions from my Citibank account

Claude will automatically select the Citibank account.

Search for Specific Merchants

Find all my Starbucks purchases from last month

Claude will use plaid_search_transactions with merchant and date filters.

Filter by Amount

Show me all transactions over $100 in December 2024

Claude will search with amount and date filters.

View Transaction Categories

What categories does Plaid use for transactions?

Claude will use plaid_get_transaction_categories.

Filter by Category

List all my travel expenses from Q4 2024

Claude will search for transactions in travel-related categories.

Tool Details

plaid_sync_transactions

Purpose: Retrieve all transaction updates since last cursor position.

Parameters:

access_token (required): Your Plaid access token
cursor (optional): Pagination cursor from previous sync
count (optional): Transactions per page (default: 100, max: 500)
account_ids (optional): Filter to specific accounts
date_start (optional): Start date (YYYY-MM-DD)
date_end (optional): End date (YYYY-MM-DD)
response_format (optional): "markdown" or "json" (default: markdown)

Returns:

Added transactions (new since last sync)
Modified transactions (updated since last sync)
Removed transactions (deleted since last sync)
Next cursor for incremental syncing

plaid_get_transaction_categories

Purpose: Get the complete taxonomy of Plaid transaction categories.

Parameters: None

Returns:

Hierarchical list of all categories
Category IDs and full paths (e.g., "Food and Drink > Restaurants > Coffee Shop")

plaid_search_transactions

Purpose: Search and filter transactions by multiple criteria.

Parameters:

access_token (required): Your Plaid access token
merchant_name (optional): Filter by merchant (partial match)
category (optional): Filter by category (partial match)
min_amount (optional): Minimum transaction amount
max_amount (optional): Maximum transaction amount
date_start (optional): Start date (YYYY-MM-DD)
date_end (optional): End date (YYYY-MM-DD)
account_ids (optional): Filter to specific accounts
response_format (optional): "markdown" or "json" (default: markdown)

Returns:

Filtered list of matching transactions
Summary of filters applied and match count

Environment Configuration

Switching Between Sandbox and Production

By default, the server uses Plaid's production API. To use sandbox for testing:

Edit plaid_mcp.py line 26:

# For sandbox testing
PLAID_API_URL = "https://sandbox.plaid.com"

# For production
PLAID_API_URL = "https://production.plaid.com"

Sandbox Test Users

Plaid provides test users in sandbox mode:

user_good - Standard test user with transactions
user_transactions_dynamic - Generates new transactions on refresh

Error Handling

The server provides clear, actionable error messages:

Invalid access token: "The token may have expired. Re-link the account via Plaid Link."
Rate limit exceeded: "Plaid limits to 100 requests/minute. Wait 60 seconds."
Item login required: "User needs to re-authenticate via Plaid Link."
Missing keychain credential: Provides exact command to store the credential

Troubleshooting

"Failed to retrieve from keychain"

Make sure you've stored all three values in Keychain:

# Verify credentials are stored
security find-generic-password -s "PLAID_CLIENT_ID" -w
security find-generic-password -s "PLAID_SECRET" -w

"Invalid access token"

Your access token may have expired. You'll need to:

Have the user re-authenticate via Plaid Link
Exchange the new public token for a fresh access token
Update the keychain with the new token

"Rate limit exceeded"

Plaid limits requests to 100 per minute in production. Wait 60 seconds before retrying.

Server not appearing in Claude Desktop

Check the config file path is correct
Verify the Python path in the config
Restart Claude Desktop completely
Check Claude Desktop logs for errors

Development

Testing the Server

# Check syntax
python -m py_compile plaid_mcp.py

# Run the server (will hang waiting for stdio - this is normal)
python plaid_mcp.py

Code Structure

Utility Functions: Keychain access, API requests, error handling, formatting
Pydantic Models: Input validation for all tools
Tool Implementations: Three main tools with comprehensive docstrings
Error Handling: Clear, actionable error messages throughout

Security Best Practices

✅ DO:

Store credentials in macOS Keychain
Use environment-specific API URLs (sandbox vs. production)
Validate all inputs with Pydantic models
Handle errors gracefully with clear messages

❌ DON'T:

Store credentials in .env files
Commit credentials to git
Hardcode API keys in code
Expose sensitive data in error messages

Resources

License

This MCP server is provided as-is for use with Plaid's Transactions API. Make sure to comply with Plaid's terms of service and API usage policies.

Plaid Transactions MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with Plaid's Transactions API. This server enables Claude to sync, search, and analyze your financial transactions securely.

Features

🛠️ Four Powerful Tools

plaid_list_accounts - List all your linked Plaid accounts
- Shows all accounts stored in keychain
- Displays friendly names (e.g., "American Express", "Citibank")
- Use this to see which accounts you can query
plaid_sync_transactions - Sync all transactions with automatic pagination
- Retrieves added, modified, and removed transactions
- Supports filtering by account and date range
- Handles cursor-based pagination automatically
- Works with multiple accounts - specify by name
- Returns data in Markdown or JSON format
plaid_get_transaction_categories - Get Plaid's transaction category taxonomy
- Shows all available categories and their hierarchy
- Useful for understanding transaction categorization
- No authentication required
plaid_search_transactions - Search and filter transactions intelligently
- Filter by merchant name, category, amount range, or date
- Supports partial matching for merchant and category searches
- Works with multiple accounts - specify by name
- Combines sync + filtering in one operation

🔐 Security Features

Stores credentials in macOS Keychain (never in files)
No credentials in code or environment files
Follows secure credential management best practices

⚡ Smart Features

Automatic pagination - Fetches all data without manual paging
Response truncation - Handles large datasets gracefully with helpful guidance
Clear error messages - Actionable error messages guide you to solutions
Dual output formats - Human-readable Markdown or machine-readable JSON

Installation

1. Install Dependencies

cd ~/plaid-transactions-mcp
pip install -r requirements.txt

2. Set Up Plaid Credentials in Keychain

You need to store three values in macOS Keychain:

# Store your Plaid Client ID
security add-generic-password -s "PLAID_CLIENT_ID" -a "plaid" -w "your_client_id_here"

# Store your Plaid Secret
security add-generic-password -s "PLAID_SECRET" -a "plaid" -w "your_secret_here"

# Store your Plaid Access Token (obtained after linking an account)
security add-generic-password -s "PLAID_ACCESS_TOKEN" -a "plaid" -w "access-sandbox-xxx"

Where to get these values:

Client ID & Secret: Get from Plaid Dashboard
Access Token: Obtained after a user completes Plaid Link flow (see below)

3. Getting an Access Token

To get transactions, you first need an access token by having a user link their bank account:

Create a Link Token using /link/token/create with transactions in the products array
User completes Plaid Link flow in your app
Exchange the public token for an access token using /item/public_token/exchange
Store the access token in Keychain

For testing, use Plaid Sandbox credentials.

4. Configure Claude Desktop

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "plaid-transactions": {
      "command": "python",
      "args": ["/Users/sfinnerty/plaid-transactions-mcp/plaid_mcp.py"]
    }
  }
}

5. Restart Claude Desktop

After updating the config, restart Claude Desktop to load the MCP server.

Usage Examples

List Your Accounts

What Plaid accounts do I have?

Claude will use plaid_list_accounts to show all your linked accounts.

Sync All Recent Transactions

Show me my recent American Express transactions

Claude will use plaid_sync_transactions with the American Express account.

Show me all transactions from my Citibank account

Claude will automatically select the Citibank account.

Search for Specific Merchants

Find all my Starbucks purchases from last month

Claude will use plaid_search_transactions with merchant and date filters.

Filter by Amount

Show me all transactions over $100 in December 2024

Claude will search with amount and date filters.

View Transaction Categories

What categories does Plaid use for transactions?

Claude will use plaid_get_transaction_categories.

Filter by Category

List all my travel expenses from Q4 2024

Claude will search for transactions in travel-related categories.

Tool Details

plaid_sync_transactions

Purpose: Retrieve all transaction updates since last cursor position.

Parameters:

access_token (required): Your Plaid access token
cursor (optional): Pagination cursor from previous sync
count (optional): Transactions per page (default: 100, max: 500)
account_ids (optional): Filter to specific accounts
date_start (optional): Start date (YYYY-MM-DD)
date_end (optional): End date (YYYY-MM-DD)
response_format (optional): "markdown" or "json" (default: markdown)

Returns:

Added transactions (new since last sync)
Modified transactions (updated since last sync)
Removed transactions (deleted since last sync)
Next cursor for incremental syncing

plaid_get_transaction_categories

Purpose: Get the complete taxonomy of Plaid transaction categories.

Parameters: None

Returns:

Hierarchical list of all categories
Category IDs and full paths (e.g., "Food and Drink > Restaurants > Coffee Shop")

plaid_search_transactions

Purpose: Search and filter transactions by multiple criteria.

Parameters:

access_token (required): Your Plaid access token
merchant_name (optional): Filter by merchant (partial match)
category (optional): Filter by category (partial match)
min_amount (optional): Minimum transaction amount
max_amount (optional): Maximum transaction amount
date_start (optional): Start date (YYYY-MM-DD)
date_end (optional): End date (YYYY-MM-DD)
account_ids (optional): Filter to specific accounts
response_format (optional): "markdown" or "json" (default: markdown)

Returns:

Filtered list of matching transactions
Summary of filters applied and match count

Environment Configuration

Switching Between Sandbox and Production

By default, the server uses Plaid's production API. To use sandbox for testing:

Edit plaid_mcp.py line 26:

# For sandbox testing
PLAID_API_URL = "https://sandbox.plaid.com"

# For production
PLAID_API_URL = "https://production.plaid.com"

Sandbox Test Users

Plaid provides test users in sandbox mode:

user_good - Standard test user with transactions
user_transactions_dynamic - Generates new transactions on refresh

Error Handling

The server provides clear, actionable error messages:

Invalid access token: "The token may have expired. Re-link the account via Plaid Link."
Rate limit exceeded: "Plaid limits to 100 requests/minute. Wait 60 seconds."
Item login required: "User needs to re-authenticate via Plaid Link."
Missing keychain credential: Provides exact command to store the credential

Troubleshooting

"Failed to retrieve from keychain"

Make sure you've stored all three values in Keychain:

# Verify credentials are stored
security find-generic-password -s "PLAID_CLIENT_ID" -w
security find-generic-password -s "PLAID_SECRET" -w

"Invalid access token"

Your access token may have expired. You'll need to:

Have the user re-authenticate via Plaid Link
Exchange the new public token for a fresh access token
Update the keychain with the new token

"Rate limit exceeded"

Plaid limits requests to 100 per minute in production. Wait 60 seconds before retrying.

Server not appearing in Claude Desktop

Check the config file path is correct
Verify the Python path in the config
Restart Claude Desktop completely
Check Claude Desktop logs for errors

Development

Testing the Server

# Check syntax
python -m py_compile plaid_mcp.py

# Run the server (will hang waiting for stdio - this is normal)
python plaid_mcp.py

Code Structure

Utility Functions: Keychain access, API requests, error handling, formatting
Pydantic Models: Input validation for all tools
Tool Implementations: Three main tools with comprehensive docstrings
Error Handling: Clear, actionable error messages throughout

Security Best Practices

✅ DO:

Store credentials in macOS Keychain
Use environment-specific API URLs (sandbox vs. production)
Validate all inputs with Pydantic models
Handle errors gracefully with clear messages

❌ DON'T:

Store credentials in .env files
Commit credentials to git
Hardcode API keys in code
Expose sensitive data in error messages

Resources

License

This MCP server is provided as-is for use with Plaid's Transactions API. Make sure to comply with Plaid's terms of service and API usage policies.