Financial Assistant

An AI-powered financial assistant that lets you ask questions about stocks in natural language and get real-time market data.

The project combines Claude, Model Context Protocol (MCP), EODHD, and Gradio into a small end-to-end application. Instead of hard-coding individual API calls into the interface, the AI can decide when it needs to use an MCP tool to retrieve financial data.

---

What it does

You can ask questions such as:

• What's Apple's current price?
• How much is Tesla trading at?
• What's Microsoft's stock price?
• Give me the latest price for AAPL.

The assistant interprets the request, calls the appropriate MCP tool, retrieves the market data from EODHD, and presents the result through a custom Gradio interface.

---

How it works

The application is split into a few simple layers:

User
  │
  ▼
Gradio Interface
  │
  ▼
Claude AI Agent
  │
  │ decides which tool to use
  ▼
MCP Client
  │
  ▼
MCP Financial Server
  │
  ▼
EODHD API
  │
  ▼
Market Data
  │
  ▼
Claude
  │
  ▼
Gradio UI

The important part of the architecture is the separation between the AI agent and the actual financial data retrieval.

Claude doesn't directly contain the EODHD API logic. Instead, it can request the get_stock_price MCP tool, which handles the data retrieval.

---

Tech Stack

Technology	Purpose
Python	Core application
Claude	AI reasoning and tool selection
MCP	Communication between the AI agent and financial tools
EODHD	Financial market data
Gradio	Web interface
Plotly	Market data visualization
HTTPX	HTTP requests
python-dotenv	Environment variable management

---

Project Structure

financial-assistant/
│
├── README.md
├── requirements.txt
├── .gitignore
│
└── src/
    └── financial_assistant/
        │
        ├── __init__.py
        ├── main.py
        ├── assistant.py
        ├── agent.py
        ├── client.py
        ├── server.py
        ├── config.py
        │
        ├── services/
        │   └── eodhd.py
        │
        └── tools/
            └── finance.py

Main components

main.py — Entry point for the application; launches the Gradio interface.

assistant.py — The Gradio frontend. Handles the user interface, chat interaction, market information cards, and visualizations.

agent.py — Connects Claude with the MCP server and manages the agent/tool-calling flow.

server.py — Defines the MCP server and exposes financial functionality as MCP tools.

client.py — MCP client used to communicate with the financial MCP server.

tools/finance.py — Contains the application-level financial tool functions.

services/eodhd.py — Handles communication with the EODHD API.

config.py — Loads API credentials from environment variables.

---

MCP Tool

The project currently exposes the following MCP tool:

get_stock_price

Retrieves the latest available price for a stock.

Example input:

{
  "symbol": "AAPL.US"
}

Other examples:

TSLA.US
MSFT.US
AMZN.US
NVDA.US

The MCP layer keeps the external financial API separate from the AI agent, making it easier to add more financial tools later.

---

Getting Started

1. Clone the repository

git clone https://github.com/faiez123tariq/financial-assistant.git
cd financial-assistant

2. Create a virtual environment

Windows:

python -m venv .venv
.venv\Scripts\activate

macOS / Linux:

python -m venv .venv
source .venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

---

Environment Variables

Create a .env file in the project root:

ANTHROPIC_API_KEY=your_anthropic_api_key
EODHD_API_KEY=your_eodhd_api_key

The application reads these values through environment variables.

Never commit your .env file to GitHub. The repository already includes .env in .gitignore.

---

Running the application

Start the Gradio application with:

python -m src.financial_assistant.main

The application will start locally at:

http://127.0.0.1:7860

Open the address in your browser and try:

What's Apple's price?

or:

What's Tesla's price?

---

Example MCP Flow

A typical request looks like this:

User:
"What's Apple's price?"

        ↓
Claude identifies that market data is required
        ↓
Claude requests: get_stock_price("AAPL.US")
        ↓
MCP server receives the request
        ↓
EODHD API is called
        ↓
Market data is returned
        ↓
Claude generates the response
        ↓
Gradio displays the result

This approach makes the project more extensible than putting every API operation directly inside the frontend.

---

Interface

The frontend was designed to be intentionally different from a standard ChatGPT-style Gradio interface.

It uses a simple beige / white / brown color palette with separate areas for:

• AI conversation
• Current market information
• Price visualization

The goal was to keep the interface clean while still making the financial information easy to scan.

---

Current Features

• Natural-language stock queries
• Claude-powered responses
• MCP tool calling
• EODHD market data
• Real-time stock price lookup
• Interactive Gradio interface
• Plotly-based market visualization
• Conversation history
• Environment-based API credentials
• Modular project structure

---

Future Improvements

More financial tools

get_company_profile()
get_historical_prices()
get_stock_fundamentals()
get_dividends()
get_market_news()

Portfolio tracking

Allow users to add stocks and track:

• Portfolio value
• Profit/loss
• Allocation
• Individual holdings

Stock comparison

Compare Apple and Microsoft.

The assistant could retrieve data for both companies and present the results side by side.

Financial news

An additional MCP tool could retrieve relevant market news and allow Claude to summarize it.

More visualizations

• Historical price charts
• Moving averages
• Volume
• Market performance
• Portfolio allocation

---

Why MCP?

One of the main reasons for building this project was to understand how MCP can be used to connect an AI model with external tools.

Instead of building a single application where the model, API calls, and UI are tightly coupled, MCP provides a clean boundary between the AI and the tools it can use. That makes it easier to add new capabilities without rewriting the entire application.

---

Security

API credentials are loaded from environment variables rather than being hard-coded into the source code.

Before pushing changes to GitHub, make sure your .env file is ignored:

.env
.venv/
__pycache__/

If an API key is accidentally pushed to a public repository, revoke it and generate a new one immediately.

---

Author

Faiez Tariq

Computer Science | AI/ML | Generative AI | MCP | Computer Vision

GitHub: https://github.com/faiez123tariq

---

License

This project is available for learning and personal use.