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

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

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

```json
{
  "symbol": "AAPL.US"
}
```

Other examples:

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

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

### 2. Create a virtual environment

Windows:

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

macOS / Linux:

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

### 3. Install dependencies

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

---

## Environment Variables

Create a `.env` file in the project root:

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

```bash
python -m src.financial_assistant.main
```

The application will start locally at:

```text
http://127.0.0.1:7860
```

Open the address in your browser and try:

```text
What's Apple's price?
```

or:

```text
What's Tesla's price?
```

---

## Example MCP Flow

A typical request looks like this:

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

![Financial Assistant](assets/financial-assistant.png)

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

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

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

```gitignore
.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](https://github.com/faiez123tariq)

---

## License

This project is available for learning and personal use.