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

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

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

Yodlee Developer Account (for API access)
ElevenLabs Account (optional, for real-time audio generation)
OpenAI Account (optional, alternative TTS provider)

Setup Instructions

1. Clone the Repository

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

2. Create a Virtual Environment

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

3. Install Dependencies

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:

cp .env.example .env

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

---

Obtaining API Keys

Yodlee API Credentials

Visit the Yodlee Developer Portal

Go to https://developer.yodlee.com

Create a Developer Account

Click "Sign Up" or "Get Started"
Fill in your details and verify your email

Access the Sandbox Environment

After logging in, navigate to the Dashboard
Look for "Sandbox" or "Development" environment

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

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

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.

Create an ElevenLabs Account

Go to https://elevenlabs.io
Click "Sign Up" and create a free account

Get Your API Key

Navigate to https://elevenlabs.io/app/settings/api-keys
Click "Create new secret key"
Copy the API key → ELEVENLABS_API_KEY

Choose a Voice ID

Browse voices at 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

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.

Create an OpenAI Account

Go to https://platform.openai.com
Sign up or log in to your account

Get Your API Key

Navigate to 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

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:

# 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

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

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:

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:

{
  "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.

python app.py

Keep this terminal window open while using Claude Desktop.

Step 6: Restart Claude Desktop

After saving the configuration file:

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

Relaunch Claude Desktop

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

Check Environment Variables

   python yodlee_client.py

This runs a self-test that verifies:

Authentication with Yodlee API
Fetching accounts
Fetching transactions
Generating spending summaries

Test Audio Generation (if ElevenLabs is configured)

   python audio_generator.py

This tests the ElevenLabs integration and saves a test audio file.

Run Unit Tests

# 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 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 file for details.

---

Yodlee MCP Server