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

1. 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

2. 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

3. 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

4. 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:

1. Create a Link Token using /link/token/create with transactions in the products array
2. User completes Plaid Link flow in your app
3. Exchange the public token for an access token using /item/public_token/exchange
4. 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:

1. Have the user re-authenticate via Plaid Link
2. Exchange the new public token for a fresh access token
3. 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

1. Check the config file path is correct
2. Verify the Python path in the config
3. Restart Claude Desktop completely
4. 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

• Plaid Transactions API Docs
• Plaid Dashboard
• MCP Documentation
• FastMCP Python SDK

---

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.