Content
# plaid-mcp
A Model Context Protocol (MCP) server that exposes Plaid sandbox transactions for AI agents.
## Overview
This MCP server wraps Plaid's sandbox environment, providing 3 task-shaped tools that AI agents can use to query financial data without managing Plaid tokens directly.
## Tools
| Tool | Description | Arguments |
|------|-------------|-----------|
| `list_accounts` | Returns all sandbox accounts with balances | None |
| `list_recent_transactions` | Returns recent transactions | `days_back: int (1-365, default 30)` |
| `list_transactions_by_category` | Filtered transactions by category | `category: str`, `days_back: int` |
## Quickstart
### 1. Get Plaid Sandbox Credentials
1. Sign up at https://dashboard.plaid.com/signup
2. Navigate to **Developers → Keys**
3. Copy your **client_id** and **Sandbox secret**
### 2. Configure Environment
```bash
cp .env.example .env
# Edit .env with your credentials
```
### 3. Install and Run
```bash
# Install dependencies
uv sync
# Run in stdio mode (for Claude Code / orchestrators)
uv run python server.py
# Or run in HTTP mode
MCP_TRANSPORT=streamable-http uv run python server.py
```
## Use with Claude Code
```bash
claude mcp add plaid-mcp uv run python /path/to/plaid-mcp/server.py
```
Example prompts:
- "What accounts do I have?"
- "How much did I spend on food this month?"
- "Show me my recent transactions"
## Use with Docker
```bash
docker compose up
```
The server will be available at `http://localhost:8001/mcp`.
## Architecture
- **Singleton token pattern**: The server mints a Plaid sandbox access token on first use and caches it at `.cache/plaid.json`. Agents don't need to manage tokens.
- **Task-shaped tools**: 3 high-level tools instead of raw Plaid API endpoints.
- **Dual transport**: stdio for subprocess orchestration, streamable-http for Docker/HTTP clients.
## License
MIT
