Conversational Finance Assistant (FastMCP + Langchain + Streamlit)

<!-- Choose a license! MIT is common -->

This project demonstrates building a conversational financial assistant capable of retrieving real-time stock quotes, news headlines, and market mover data using natural language queries.

It features a decoupled architecture:

• Backend: A secure server built with FastMCP acting as a gateway to financial APIs (Finnhub, Alpha Vantage).
• Frontend: A user-friendly web interface built with Streamlit.
• Agent: Powered by Langchain and the OpenAI API (GPT models) to understand user requests, utilize backend tools, and generate conversational responses.

Technical Report: Report

Features

• Natural Language Queries: Ask questions like:
  • "What's the price of Apple?"
  • "How is MSFT doing today?"
  • "Any recent news for TSLA?"
  • "Show me the top gainers today."
  • "What's the market news?"
• Real-time Data: Fetches current stock quotes, recent news, and market movers via external APIs.
• Secure API Key Management: Financial API keys are stored securely on the backend MCP server, not exposed in the frontend or to the LLM.
• Conversational Responses: The LLM synthesizes data fetched via tools into easy-to-understand answers.
• Follow-up Suggestions: Provides relevant next questions to continue the conversation.
• Modular Architecture: Decouples the UI/Agent logic from the backend data fetching logic using the Model Context Protocol (MCP).

Architecture

The system uses a client-server architecture orchestrated by a Langchain agent:

1. User Interface (Streamlit): Handles chat display, user input, and suggestion buttons.
2. Langchain Agent Executor: Resides in the Streamlit app. Uses ChatOpenAI and defined StructuredTools. Manages the conversation flow, calls the LLM, and executes tools when requested.
3. OpenAI LLM: Interprets user intent, decides when to call tools, synthesizes final responses from tool results.
4. Langchain Tools (in UI): Python functions (get_price, get_news, get_market_movers) defined within the UI code. These tools are invoked by the Agent Executor.
5. FastMCP Client (in UI Tools): The Langchain tools use fastmcp.Client to communicate with the backend MCP server.
6. FastMCP Server (Backend): A separate Python process (fin_server_v2.py). Exposes financial data fetching capabilities as secure MCP Tools (@mcp.tool()) and Resources (@mcp.resource()). Handles interaction with external financial APIs.
7. Financial APIs: Finnhub and Alpha Vantage (can be extended).

Setup and Installation

Prerequisites:

• Python 3.10+
• uv (recommended) or pip
• API Keys:
  • OpenAI API Key (platform.openai.com/account/api-keys)
  • Finnhub API Key (finnhub.io)
  • Alpha Vantage API Key (alphavantage.co)

Steps:

1. Clone the Repository:

   git clone <your-repo-url>
   cd <your-repo-name>
   

2. Create .env File: Create a file named .env in the project root and add your API keys:

   # .env file
   FINNHUB_API_KEY=YOUR_FINNHUB_KEY
   ALPHA_VANTAGE_API_KEY=YOUR_ALPHA_VANTAGE_KEY
   OPENAI_API_KEY=sk-YOUR_OPENAI_KEY
   

   (Replace the placeholder values with your actual keys)

3. Create Virtual Environment:

   uv venv # Creates a .venv folder
   source .venv/bin/activate # On Linux/macOS
   # .\venv\Scripts\activate # On Windows CMD/PowerShell
   

4. Install Dependencies:

   uv pip install -r requirements.txt
   # OR if you don't have a requirements.txt yet:
   # uv pip install streamlit "fastmcp" httpx python-dotenv pydantic-settings openai langchain langchain-openai pydantic langchainhub "langchain-community"
   

   (See requirements.txt for specific tested versions)

Running the Application

You need to run the backend MCP server and the frontend Streamlit UI separately.

1. Run the Backend MCP Server: Open a terminal, activate the virtual environment, and run:

   python fin_server_v2.py
   

   Keep this terminal window open. You should see log messages indicating it started successfully and loaded API keys.

2. Run the Frontend Streamlit UI: Open a second terminal window, activate the same virtual environment, and run:

   streamlit run fin_langchain_v2.py
   

   Streamlit will provide a local URL (usually http://localhost:8501). Open this URL in your web browser.

3. Interact: Start asking financial questions in the chat interface!

Code Structure

• fin_server_v2.py: The backend FastMCP server application. Contains tool and resource definitions, interacts with financial APIs.
• fin_langchain_v2.py: The frontend Streamlit application. Contains the Langchain agent setup, UI components, and helper functions to call the MCP server.
• .env (You create this): Stores API keys securely.
• requirements.txt (You create this or use the one provided): Lists Python dependencies.

Future Improvements

• Add more financial tools (historical data, fundamentals, analyst ratings).
• Implement more sophisticated error handling and API fallback logic.
• Improve NLU for ticker/company name recognition.
• Integrate Langchain memory more deeply for multi-turn context.
• Add data visualization (charts) to the Streamlit UI.
• Implement server-side caching for financial APIs.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request or open an Issue.

License

This project is licensed under the MIT License. <!-- Choose and add a LICENSE file -->