Plaid Transactions MCP Server

# 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 ```bash 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: ```bash # 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](https://dashboard.plaid.com/developers/keys) - **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](https://plaid.com/docs/sandbox/) credentials. ### 4. Configure Claude Desktop Add this to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`): ```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: ```python # 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: ```bash # 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 ```bash # 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](https://plaid.com/docs/transactions/) - [Plaid Dashboard](https://dashboard.plaid.com/) - [MCP Documentation](https://modelcontextprotocol.io/) - [FastMCP Python SDK](https://github.com/modelcontextprotocol/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.