---
title: Yodlee MCP Server
emoji: 🏦
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.33.0
python_version: "3.11"
app_file: app.py
pinned: false
tags:
  - mcp
  - building-mcp-track-enterprise
  - building-mcp-track-consumer
  - building-mcp-track-creative
  - model-context-protocol
  - yodlee
  - gradio
---

# 🏦 Yodlee MCP Server

> **[See the demo live on Hugging Face](https://huggingface.co/spaces/ashishmerani/yodlee-mcp-server-main)**

A Gradio-based MCP (Model Context Protocol) server that connects Claude Desktop to Yodlee banking data, with text-to-speech audio summaries powered by ElevenLabs and OpenAI TTS.

## Demo

<div align="center">
  <a href="https://www.loom.com/share/376d6e442a5f41da9f831e44b8c18784">
    <img src="https://cdn.loom.com/sessions/thumbnails/376d6e442a5f41da9f831e44b8c18784-35fddb873ae0ce24.jpg" alt="Yodlee MCP Server Demo" width="600">
  </a>
</div>

## Overview

This application serves as a bridge between Claude Desktop and the Yodlee financial data API. It exposes 7 MCP tools that allow Claude to:

- List and switch between available test user accounts
- Retrieve linked financial accounts and balances
- Query transaction history with filtering options
- Generate spending summaries by category
- Create audio narrations of spending summaries using ElevenLabs or OpenAI text-to-speech

The application includes a Gradio web UI for interactive exploration and testing, while also functioning as an MCP server for Claude Desktop integration.

---

## MCP Tools Reference

When used via Claude Desktop, the following tools are available:

| Tool | Description |
|------|-------------|
| `list_available_users()` | List all test user accounts |
| `get_current_user()` | Get the currently active user |
| `switch_user(login_name)` | Switch to a different user account |
| `get_accounts(login_name?, account_type?)` | Get linked financial accounts |
| `get_transactions(login_name?, from_date?, to_date?, category_type?)` | Get transaction history |
| `get_spending_summary(login_name?, from_date?, to_date?)` | Get spending by category |
| `generate_audio_summary(login_name?, from_date?, to_date?, custom_script?)` | Generate audio summary |

---

## Usage Guide

### Gradio Web UI

The web interface provides 5 tabs:

#### 📊 Accounts Tab
- View all linked financial accounts
- Filter by account type (bank, creditCard, investment, insurance, loan)
- See account balances and institution names

#### 💳 Transactions Tab
- Browse transaction history
- Filter by date range and category type (EXPENSE, INCOME, TRANSFER)
- **Note**: Sandbox data is from 2013-01-01 to 2014-12-31

#### 📈 Spending Summary Tab
- View spending grouped by category
- Categories sorted by total amount (highest first)
- Shows transaction counts per category

#### 🎧 Audio Summary Tab
- Generate spoken spending summaries with two TTS providers:
  - **ElevenLabs TTS**: High-quality voices with natural intonation
  - **OpenAI TTS**: Reliable, cost-effective option with 6 voice choices
- In **Demo Mode**: Plays provider-specific pre-generated samples (no API key required)
- In **Live Mode**: Generates real-time audio with your actual spending data

#### 🎬 Demo Video Tab
- Watch a demonstration of the application (see [Demo](#demo) above)

### Switching Users

Use the **Active User** dropdown in the header to switch between test accounts. Each user has different linked accounts and transaction histories.

### Sandbox Date Constraints

⚠️ **Important**: The Yodlee sandbox only contains historical test data from **2013-01-01 to 2014-12-31**.

- Dates outside this range are automatically adjusted
- The UI shows warnings when dates are clamped
- Use dates within this range for accurate results

---

## Prerequisites

### System Requirements
- **Python**: 3.10 or higher
- **Operating System**: macOS, Linux, or Windows
- **Internet Connection**: Required for API calls

### Required Accounts
1. **Yodlee Developer Account** (for API access)
2. **ElevenLabs Account** (optional, for real-time audio generation)
3. **OpenAI Account** (optional, alternative TTS provider)

## Setup Instructions

### 1. Clone the Repository

```bash
git clone https://github.com/ashishmerani/yodlee-mcp-server.git
cd yodlee-mcp-server
```

### 2. Create a Virtual Environment

```bash
python -m venv venv
source venv/bin/activate  # On macOS/Linux
# or
.\venv\Scripts\activate   # On Windows
```

### 3. Install Dependencies

```bash
pip install -r requirements.txt
```

This installs:
- `gradio[mcp]>=6.0.0` - Web UI framework with MCP support (the `[mcp]` extra is required for Claude Desktop integration)
- `requests>=2.31.0` - HTTP client for API calls
- `python-dotenv>=1.0.0` - Environment variable management
- `elevenlabs>=2.0.0` - ElevenLabs text-to-speech API client
- `openai>=1.0.0` - OpenAI text-to-speech API client

> **Note for zsh users (macOS default shell):** If installing packages directly with extras like `pip install gradio[mcp]`, you must quote the package name to prevent shell interpretation of square brackets:
> ```bash
> pip install "gradio[mcp]"
> ```
> This is not needed when using `pip install -r requirements.txt` since the shell doesn't parse the file contents.

### 4. Configure Environment Variables

Copy the example environment file:

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

Then edit `.env` with your actual credentials (see Configuration section below).

---

## Obtaining API Keys

### Yodlee API Credentials

1. **Visit the Yodlee Developer Portal**
   - Go to [https://developer.yodlee.com](https://developer.yodlee.com)

2. **Create a Developer Account**
   - Click "Sign Up" or "Get Started"
   - Fill in your details and verify your email

3. **Access the Sandbox Environment**
   - After logging in, navigate to the Dashboard
   - Look for "Sandbox" or "Development" environment

4. **Generate API Credentials**
   - Navigate to **API Credentials** or **Applications** section
   - Create a new application if needed
   - Copy the following values:
     - **Client ID** → `YODLEE_CLIENT_ID`
     - **Client Secret** → `YODLEE_CLIENT_SECRET`

5. **Get Test User Login Names**
   - In the Sandbox, navigate to **Test Users** or **User Management**
   - Yodlee provides pre-configured test users with sample financial data
   - Copy the login names (e.g., `sbMemuser1`, `sbMemuser2`, etc.)
   - These go into `YODLEE_LOGIN_NAMES`

6. **Note the Base URL**
   - The sandbox base URL is: `https://sandbox.api.yodlee.com/ysl`
   - This is already set in `.env.example`

### ElevenLabs API Key (Optional)

The ElevenLabs API is **optional**. Without it, the app runs in "demo mode" using a pre-generated audio sample.

1. **Create an ElevenLabs Account**
   - Go to [https://elevenlabs.io](https://elevenlabs.io)
   - Click "Sign Up" and create a free account

2. **Get Your API Key**
   - Navigate to [https://elevenlabs.io/app/settings/api-keys](https://elevenlabs.io/app/settings/api-keys)
   - Click "Create new secret key"
   - Copy the API key → `ELEVENLABS_API_KEY`

3. **Choose a Voice ID**
   - Browse voices at [https://elevenlabs.io/voice-library](https://elevenlabs.io/voice-library)
   - Click on a voice to view its details
   - Copy the Voice ID from the URL or voice details
   - Recommended voices for financial summaries:
     - **Chris** (`iP95p4xoKVk53GoZ742B`): Natural, conversational American male
     - **Eric** (`cjVigY5qzO86Huf0OWal`): Smooth, professional tone
     - **Lily** (`pFZP5JQG7iQjIQuC4Bku`): Warm British female

4. **Free Tier Limits**
   - 10,000 characters/month (~20-25 audio summaries)
   - Each summary uses approximately 400-800 characters

### OpenAI API Key (Optional)

OpenAI TTS is an **alternative** to ElevenLabs. You can configure one or both providers.

1. **Create an OpenAI Account**
   - Go to [https://platform.openai.com](https://platform.openai.com)
   - Sign up or log in to your account

2. **Get Your API Key**
   - Navigate to [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys)
   - Click "Create new secret key"
   - **Important**: Ensure the key has the `model.request` scope for TTS access
   - Copy the API key → `OPENAI_API_KEY`

3. **Choose a Voice**
   - Available voices: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`
   - Recommended for financial summaries:
     - **onyx**: Deep, authoritative male voice
     - **nova**: Warm, expressive female voice
     - **alloy**: Balanced, neutral tone
   - Set your choice → `OPENAI_TTS_VOICE`


---

## Configuration

### Environment Variables

Create a `.env` file in the project root with the following variables:

```env
# Yodlee Sandbox API Credentials (Required)
YODLEE_CLIENT_ID=your_client_id_here
YODLEE_CLIENT_SECRET=your_client_secret_here
YODLEE_LOGIN_NAMES=user1,user2,user3
YODLEE_BASE_URL=https://sandbox.api.yodlee.com/ysl

# ElevenLabs Text-to-Speech (Optional - Provider 1)
ELEVENLABS_API_KEY=your_elevenlabs_api_key_here
ELEVENLABS_VOICE_ID=iP95p4xoKVk53GoZ742B

# OpenAI Text-to-Speech (Optional - Provider 2)
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_TTS_VOICE=onyx
```

### Variable Descriptions

| Variable | Required | Description |
|----------|----------|-------------|
| `YODLEE_CLIENT_ID` | Yes | Your Yodlee API client ID |
| `YODLEE_CLIENT_SECRET` | Yes | Your Yodlee API secret key |
| `YODLEE_LOGIN_NAMES` | Yes | Comma-separated list of test user login names |
| `YODLEE_BASE_URL` | Yes | Yodlee API base URL (use sandbox URL for testing) |
| `ELEVENLABS_API_KEY` | No | ElevenLabs API key for real-time audio generation |
| `ELEVENLABS_VOICE_ID` | No* | Voice ID for ElevenLabs TTS (*Required if using ElevenLabs) |
| `OPENAI_API_KEY` | No | OpenAI API key for real-time audio generation |
| `OPENAI_TTS_VOICE` | No* | Voice name for OpenAI TTS (*Required if using OpenAI) |

### Demo Mode vs. Live Mode

Each TTS provider operates independently. You can configure one, both, or neither:

| Provider | API Key Status | Button Behavior |
|----------|----------------|-----------------|
| **ElevenLabs** | Not configured | Plays pre-generated ElevenLabs sample |
| **ElevenLabs** | Configured | Generates real-time audio via ElevenLabs API |
| **OpenAI** | Not configured | Plays pre-generated OpenAI sample |
| **OpenAI** | Configured | Generates real-time audio via OpenAI API |

---

## Running the Application

### Start the Server

```bash
python app.py
```

You should see output like:

```
============================================================
Starting Yodlee MCP Server...
============================================================

This server exposes 7 MCP tools:
  1. list_available_users - List available Yodlee test users
  2. get_current_user - Get the current active user
  3. switch_user - Switch to a different test user
  4. get_accounts - Get linked financial accounts
  5. get_transactions - Get transaction history
  6. get_spending_summary - Get spending by category
  7. generate_audio_summary - Generate audio spending summary (ElevenLabs TTS)

Available test users: ...user1, ...user2, ...user3
Gradio UI: http://localhost:7860
MCP endpoint: Available when mcp_server=True
============================================================
```

### Access the Application

- **Web UI**: Open [http://localhost:7860](http://localhost:7860) in your browser
- **MCP Endpoint**: The server automatically exposes MCP tools for Claude Desktop

---

## Claude Desktop Integration

To use this MCP server with Claude Desktop, you need to configure Claude to connect to the Gradio MCP endpoint. This allows Claude to access the 7 Yodlee tools directly from the chat interface.

### Step 1: Install mcp-remote

The `mcp-remote` package is required to bridge Claude Desktop with the Gradio MCP server:

```bash
npm install -g @modelcontextprotocol/mcp-remote
```

### Step 2: Locate the Claude Desktop Configuration File

The configuration file is located at:

```
~/Library/Application Support/Claude/claude_desktop_config.json
```

If the file doesn't exist, create it with an empty JSON object `{}`.

### Step 3: Find Required Paths

Before editing the configuration, find the paths to `node` and `mcp-remote` on your system:

```bash
which node
which mcp-remote
```

Note the paths returned — you'll need them for the configuration.

### Step 4: Edit the Configuration File

Open the configuration file in a text editor and add (or merge) the following configuration:

```json
{
  "mcpServers": {
    "yodlee-mcp-gradio": {
      "command": "/path/to/node",
      "args": [
        "/path/to/mcp-remote",
        "http://127.0.0.1:7860/gradio_api/mcp/",
        "--transport",
        "http-only"
      ]
    }
  }
}
```

**Replace the placeholder paths with your actual paths:**

- `/path/to/node` → The path from `which node` (e.g., `/usr/local/bin/node`)
- `/path/to/mcp-remote` → The path from `which mcp-remote` (e.g., `/usr/local/bin/mcp-remote`)

**Example for macOS:**
```json
{
  "mcpServers": {
    "yodlee-mcp-gradio": {
      "command": "/usr/local/bin/node",
      "args": [
        "/usr/local/bin/mcp-remote",
        "http://127.0.0.1:7860/gradio_api/mcp/",
        "--transport",
        "http-only"
      ]
    }
  }
}
```

> **Note**: If you already have other MCP servers configured, add the `yodlee-mcp-gradio` entry to your existing `mcpServers` object rather than replacing the entire file.

### Step 5: Start the Gradio Server

⚠️ **Important**: The Gradio MCP server must be running before Claude Desktop can connect to it.

```bash
python app.py
```

Keep this terminal window open while using Claude Desktop.

### Step 6: Restart Claude Desktop

After saving the configuration file:

1. **Completely quit Claude Desktop** (not just close the window): `Cmd + Q` or right-click the dock icon → Quit

2. **Relaunch Claude Desktop**

3. **Verify the connection**: In Claude Desktop, you should see the MCP tools icon (🔧) indicating available tools. Click it to see the 7 Yodlee tools.

### Troubleshooting Claude Desktop Integration

**"Server disconnected" or connection errors:**
- Ensure the Gradio server is running (`python app.py`)
- Check that the URL `http://127.0.0.1:7860/gradio_api/mcp/` is accessible in your browser
- Verify the paths in your configuration are correct

**Tools not appearing:**
- Restart Claude Desktop completely (quit and relaunch)
- Check the configuration file for JSON syntax errors
- Ensure `mcp-remote` is installed globally (`npm list -g @modelcontextprotocol/mcp-remote`)

**"Command not found" errors:**
- Use absolute paths instead of command names
- Verify the paths exist: `ls /path/to/node`

---

## Testing the Application

### Verify Setup

1. **Check Environment Variables**
   ```bash
   python yodlee_client.py
   ```
   This runs a self-test that verifies:
   - Authentication with Yodlee API
   - Fetching accounts
   - Fetching transactions
   - Generating spending summaries

2. **Test Audio Generation** (if ElevenLabs is configured)
   ```bash
   python audio_generator.py
   ```
   This tests the ElevenLabs integration and saves a test audio file.

### Run Unit Tests

```bash
# Install pytest if not already installed
pip install pytest

# Run all tests
pytest tests/

# Run specific test file
pytest tests/yodlee_mcp/test_utils.py
```

### Expected Test Behavior

- Tests use mocked API responses to avoid real API calls
- All tests should pass without requiring actual API credentials
- Mock environment variables are set up via `tests/conftest.py`

---

## Project Structure

```
sample-gradio/
├── app.py                              # Main entry point
├── yodlee_client.py                    # Yodlee API client
├── audio_generator.py                  # ElevenLabs TTS integration
├── requirements.txt                    # Python dependencies
├── .env.example                        # Example environment configuration
├── sample_audio_summary_elevenlabs.mp3 # Pre-generated ElevenLabs demo audio
├── sample_audio_summary_openai.mp3     # Pre-generated OpenAI demo audio
├── generate_openai_sample.py           # Utility to generate OpenAI sample
├── audio_outputs/                      # Generated audio files (gitignored)
├── yodlee_mcp/                         # Core package
│   ├── __init__.py
│   ├── config.py                       # Configuration and constants
│   ├── utils.py                        # Utility functions
│   ├── client_manager.py               # Client session management
│   ├── mcp_tools.py                    # MCP tool implementations
│   └── gradio_ui.py                    # Gradio interface (includes OpenAI TTS)
└── tests/                              # Unit tests
    ├── conftest.py
    └── yodlee_mcp/
        ├── test_config.py
        ├── test_utils.py
        ├── test_client_manager.py
        └── test_mcp_tools.py
```

---

## Troubleshooting

### Common Issues

**"Missing required credentials" error**
- Ensure all required environment variables are set in `.env`
- Check that `.env` file is in the project root directory
- Verify there are no typos in variable names

**"Authentication failed" error**
- Verify your `YODLEE_CLIENT_ID` and `YODLEE_CLIENT_SECRET` are correct
- Ensure your Yodlee developer account is active
- Check if the login names match valid sandbox test users

**"No transactions found" or empty results**
- Remember sandbox data is only available for 2013-2014
- Adjust date range to `2013-01-01` to `2014-12-31`

**Audio generation fails (ElevenLabs)**
- Without `ELEVENLABS_API_KEY`: App works in demo mode (this is expected)
- With API key: Check the key is valid and has available credits
- Verify `ELEVENLABS_VOICE_ID` is set when using ElevenLabs

**Audio generation fails (OpenAI)**
- Without `OPENAI_API_KEY`: App works in demo mode (this is expected)
- "Insufficient permissions" error: Your API key needs the `model.request` scope
  - Go to [OpenAI API keys](https://platform.openai.com/api-keys) and update permissions
- Verify `OPENAI_TTS_VOICE` is set to a valid voice name

**"Character quota exceeded" error**
- ElevenLabs free tier has a 10,000 character/month limit
- Wait for the monthly reset or upgrade your plan
- Alternative: Use OpenAI TTS which has pay-as-you-go pricing

---

## License

See [LICENSE](LICENSE) file for details.

---

*Powered by [Yodlee API](https://developer.yodlee.com), [Gradio](https://gradio.app), [ElevenLabs](https://elevenlabs.io), and [OpenAI](https://openai.com)*