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

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

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

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

1. Visit the Yodlee Developer Portal

• Go to https://developer.yodlee.com

1. Create a Developer Account

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

1. Access the Sandbox Environment

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

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

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

1. 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
• Click "Sign Up" and create a free account

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

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

1. 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
• Sign up or log in to your account

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

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

Demo Mode vs. Live Mode

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

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:

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

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

1. Relaunch Claude Desktop

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

   python yodlee_client.py

This runs a self-test that verifies:

• Authentication with Yodlee API
• Fetching accounts
• Fetching transactions
• Generating spending summaries

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

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