# Plaid MCP Server (Python)

A Model Context Protocol (MCP) server for integrating with Plaid's API in sandbox mode. This server provides tools for linking bank accounts, retrieving transactions, balances, and account information.

## Features

- Create Link tokens for Plaid Link initialization
- Exchange public tokens for access tokens
- Retrieve account information
- Fetch transactions within date ranges
- Get real-time balance information

## Prerequisites

- Python 3.10 or higher
- pip or uv package manager
- Plaid account with sandbox credentials

## Setup

### 1. Get Plaid Credentials

- Sign up at [Plaid Dashboard](https://dashboard.plaid.com/)
- Navigate to Developers > Keys
- Copy your `client_id` and `sandbox` secret

### 2. Install Dependencies

Using pip:
```bash
pip install -e .
```

Or using uv (faster):
```bash
uv pip install -e .
```

### 3. Configure Environment

```bash
cp .env.example .env
```

Edit `.env` and add your credentials:
```
PLAID_CLIENT_ID=your_client_id_here
PLAID_SECRET=your_sandbox_secret_here
```

## Usage

### Running the Server

```bash
python -m plaid_mcp_server.server
```

Or if installed:
```bash
plaid-mcp-server
```

### Getting a Sandbox Access Token

For testing, run the sandbox setup script:

```bash
python sandbox_setup.py
```

This will create a test Plaid item and give you an access token to use with the MCP tools.

### Available Tools

#### 1. create_link_token
Create a Link token for initializing Plaid Link.

**Parameters:**
- `user_id` (required): Unique ID for the user
- `client_name` (required): Name of your application
- `products` (optional): Array of products (default: ["transactions"])
- `country_codes` (optional): Array of country codes (default: ["US"])
- `language` (optional): Language code (default: "en")

#### 2. exchange_public_token
Exchange a public token for an access token.

**Parameters:**
- `public_token` (required): Public token from Plaid Link

#### 3. get_accounts
Retrieve account information.

**Parameters:**
- `access_token` (required): Access token for the linked item

#### 4. get_transactions
Fetch transactions within a date range.

**Parameters:**
- `access_token` (required): Access token for the linked item
- `start_date` (required): Start date (YYYY-MM-DD)
- `end_date` (required): End date (YYYY-MM-DD)

#### 5. get_balance
Get real-time balance information.

**Parameters:**
- `access_token` (required): Access token for the linked item

## Testing in Sandbox

The server is configured to use Plaid's sandbox environment. Use these test credentials when testing with Plaid Link:

- **Username:** `user_good`
- **Password:** `pass_good`

See [Plaid's Sandbox Guide](https://plaid.com/docs/sandbox/) for more test credentials and scenarios.

## Development

### Project Structure

```
plaid-mcp-python/
├── src/
│   └── plaid_mcp_server/
│       ├── __init__.py
│       └── server.py          # Main MCP server implementation
├── sandbox_setup.py            # Script to create test access tokens
├── requirements.txt            # Python dependencies
├── pyproject.toml             # Project metadata and build config
├── .env.example               # Environment variables template
└── README.md
```

### Code Style

This implementation follows Python best practices:
- Type hints for better IDE support and type checking
- Async/await for concurrent operations
- Proper error handling with specific exceptions
- PEP 8 style guide compliance
- Docstrings for all modules and functions

## Connecting to Claude Desktop

To use this MCP server with Claude Desktop, add the following to your Claude Desktop config:

**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "plaid": {
      "command": "python",
      "args": ["-m", "plaid_mcp_server.server"],
      "cwd": "/absolute/path/to/plaid-mcp-python",
      "env": {
        "PLAID_CLIENT_ID": "your_client_id_here",
        "PLAID_SECRET": "your_sandbox_secret_here"
      }
    }
  }
}
```

Or if using uv:

```json
{
  "mcpServers": {
    "plaid": {
      "command": "uv",
      "args": ["run", "plaid-mcp-server"],
      "cwd": "/absolute/path/to/plaid-mcp-python",
      "env": {
        "PLAID_CLIENT_ID": "your_client_id_here",
        "PLAID_SECRET": "your_sandbox_secret_here"
      }
    }
  }
}
```

After updating the config, restart Claude Desktop.

## License

MIT