📌Overview

Purpose: The investor-agent aims to provide comprehensive financial insights and analysis to Large Language Models through real-time market data and advanced analytics.

Overview: The investor-agent is a Model Context Protocol (MCP) server designed to facilitate detailed financial analysis and reporting. It integrates with reliable data sources to deliver critical financial information, including ticker reports, options data, historical trends, and financial statements, all formatted for user-friendly access.

Key Features:

• Detailed Ticker Reports: Delivers extensive reports on individual ticker symbols, including company overviews, performance metrics, news, and analyst recommendations, assisting users in making informed investment decisions.

• Options Data Retrieval: Provides information on stock options with the highest open interest, enabling users to identify potential trading opportunities.

• Historical Price Trends: Retrieves historical stock price information, helping users analyze past performance to make future predictions.

• Comprehensive Financial Statements: Enables access to income statements, balance sheets, and cash flow statements in millions USD, facilitating thorough financial analysis.

• Institutional Ownership Insights: Offers details on institutional and mutual fund holdings, essential for understanding stock ownership dynamics.

• Earnings History and Insider Trading Data: Supplies formatted data related to earnings history and recent insider trades, enhancing investment strategy development.

---

investor-agent: A Financial Analysis MCP Server

Overview

The investor-agent is a Model Context Protocol (MCP) server that provides comprehensive financial insights and analysis to Large Language Models. It leverages real-time market data, news, and advanced analytics to help users obtain:

• Detailed ticker reports including company overview, news, key metrics, performance, dates, analyst recommendations, and upgrades/downgrades.
• Options data highlighting high open interest.
• Historical price trends for stocks.
• Essential financial statements (income, balance sheet, cash flow) formatted in millions USD.
• Up-to-date institutional ownership and mutual fund holdings.
• Earnings history and insider trading activity.

The server integrates with yfinance for market data retrieval.

Combine this with an MCP server for placing trades on a brokerage platform such as tasty-agent to place trades on tastytrade platform. Enable web search functionality to incorporate the latest news in your analysis.

Prerequisites

• Python: 3.12 or higher
• Package Manager: uv

Installation

First, install uv if you haven't already:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then, run the investor-agent MCP server using uvx:

uvx investor-agent

Tools

The investor-agent server provides several tools to support financial analysis:

Ticker Information

1. get_ticker_data
   Retrieves a comprehensive report for a given ticker symbol, including company overview, news, key metrics, performance, dates, analyst recommendations, and upgrades/downgrades.
   Input: ticker (string): Stock ticker symbol (e.g., "AAPL").
   Return: A formatted multi-section report.

2. get_available_options
   Provides a list of stock options with the highest open interest.
   Inputs:

   • ticker_symbol (string): Stock ticker symbol.
   • num_options (int, optional): Number of options to return (default: 10).
   • start_date & end_date (string, optional): Date range in YYYY-MM-DD format.
   • strike_lower & strike_upper (float, optional): Desired strike price range.
   • option_type (string, optional): Option type ("C" for calls, "P" for puts).
     Return: A formatted table of options data.

3. get_price_history
   Retrieves historical price data for a specific ticker.
   Inputs:

   • ticker (string): Stock ticker symbol.
   • period (string): Time period (choose from "1d", "5d", "1mo", "3mo", "6mo", "1y", "2y", "5y", "10y", "ytd", "max").
     Return: A table showing price history.

Financial Data Tools

1. get_financial_statements
   Fetches financial statements (income, balance, or cash flow) formatted in millions USD.
   Inputs:

   • ticker (string): Stock ticker symbol.
   • statement_type (string): "income", "balance", or "cash".
   • frequency (string): "quarterly" or "annual".
     Return: A formatted financial statement.

2. get_institutional_holders
   Retrieves details about major institutional and mutual fund holders.
   Input: ticker (string): Stock ticker symbol.
   Return: Two formatted tables listing institutional and mutual fund holders.

3. get_earnings_history
   Retrieves a formatted table of earnings history.
   Input: ticker (string): Stock ticker symbol.
   Return: A table displaying historical earnings data.

4. get_insider_trades
   Fetches recent insider trading activity for a given ticker.
   Input: ticker (string): Stock ticker symbol.
   Return: A formatted table showing insider trades.

Usage with MCP Clients

To integrate investor-agent with an MCP client (e.g., Claude Desktop), add the following configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "investor": {
        "command": "path/to/uvx/command/uvx",
        "args": ["investor-agent"]
    }
  }
}

Debugging

You can use the MCP inspector to debug the server:

npx @modelcontextprotocol/inspector uvx investor-agent

For log monitoring, check these directories:

• macOS: ~/Library/Logs/Claude/mcp*.log
• Windows: %APPDATA%\Claude\logs\mcp*.log

Development

For local development and testing:

1. Use the MCP inspector as described above.
2. Test using Claude Desktop with this configuration:

{
  "mcpServers": {
    "investor": {
      "command": "path/to/uv/command/uv",
      "args": ["--directory", "path/to/investor-agent", "run", "investor-agent"]
    }
  }
}

License

This MCP server is licensed under the MIT License. See the LICENSE file for details.