[](https://mseep.ai/app/ferdousbhai-investor-agent)
[](https://archestra.ai/mcp-catalog/ferdousbhai__investor-agent)
# 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, fundamental and technical analysis to deliver:
- **Market Movers:** Top gainers, losers, and most active stocks with support for different market sessions
- **Ticker Analysis:** Company overview, news, metrics, analyst recommendations, and upgrades/downgrades
- **Options Data:** Filtered options chains with customizable parameters
- **Historical Data:** Price trends and earnings history
- **Financial Statements:** Income, balance sheet, and cash flow statements
- **Ownership Analysis:** Institutional holders and insider trading activity
- **Earnings Calendar:** Upcoming earnings announcements with date filtering
- **Market Sentiment:** CNN Fear & Greed Index, Crypto Fear & Greed Index, and Google Trends sentiment analysis
- **Technical Analysis:** SMA, EMA, RSI, MACD, BBANDS indicators (optional)
- **Intraday Data:** 15-minute historical stock bars via Alpaca API (optional)
The server integrates with [yfinance](https://pypi.org/project/yfinance/) for market data and automatically optimizes data volume for better performance.
## Architecture & Performance
**Robust Caching & Error Handling Strategy:**
1. **`yfinance[nospam]`** → Built-in smart caching + rate limiting for Yahoo Finance API
2. **`hishel`** → HTTP response caching for external APIs (CNN, crypto, earnings data)
3. **`tenacity`** → Retry logic with exponential backoff for transient failures
This multi-layered approach ensures reliable data delivery while respecting API rate limits and minimizing redundant requests.
## Prerequisites
- **Python:** 3.12 or higher
- **Package Manager:** [uv](https://docs.astral.sh/uv/). Install if needed:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### Optional Dependencies
- **TA-Lib C Library:** Required for technical indicators. Follow [official installation instructions](https://ta-lib.org/install/).
- **Alpaca API:** Required for intraday stock data. Get free API keys at [Alpaca Markets](https://alpaca.markets/).
## Installation
### Quick Start
```bash
# Core features only
uvx investor-agent
# With technical indicators (requires TA-Lib)
uvx "investor-agent[ta]"
# With Alpaca intraday data (requires Alpaca API keys)
uvx "investor-agent[alpaca]"
# With all optional features
uvx "investor-agent[ta,alpaca]"
```
## Tools
### Market Data
- **`get_market_movers(category="most-active", count=25, market_session="regular")`** - Market movers data including top gainers, losers, or most active stocks. Supports different market sessions (regular/pre-market/after-hours) for most-active category. Returns up to 100 stocks with cleaned percentage changes, volume, and market cap data
- **`get_ticker_data(ticker, max_news=5, max_recommendations=5, max_upgrades=5)`** - Comprehensive ticker report with essential field filtering and configurable limits for news, analyst recommendations, and upgrades/downgrades
- **`get_options(ticker_symbol, num_options=10, start_date=None, end_date=None, strike_lower=None, strike_upper=None, option_type=None)`** - Options data with advanced filtering by date range (YYYY-MM-DD), strike price bounds, and option type (C=calls, P=puts)
- **`get_price_history(ticker, period="1mo")`** - Historical OHLCV data with intelligent interval selection: daily intervals for periods ≤1y, monthly intervals for periods ≥2y to optimize data volume
- **`get_financial_statements(ticker, statement_types=["income"], frequency="quarterly", max_periods=8)`** - Financial statements with parallel fetching support. Returns dict with statement type as key
- **`get_institutional_holders(ticker, top_n=20)`** - Major institutional and mutual fund holders data
- **`get_earnings_history(ticker, max_entries=8)`** - Historical earnings data with configurable entry limits
- **`get_insider_trades(ticker, max_trades=20)`** - Recent insider trading activity with configurable trade limits
- **`get_nasdaq_earnings_calendar(date=None, limit=100)`** - Upcoming earnings announcements using Nasdaq API (YYYY-MM-DD format, defaults to today).
- **`fetch_intraday_data(stock, window=200)`** - Fetch 15-minute historical stock bars using Alpaca API. Returns CSV string with timestamp and close price data in EST timezone. Requires `investor-agent[alpaca]` installation and ALPACA_API_KEY/ALPACA_API_SECRET environment variables.
### Market Sentiment
- **`get_cnn_fear_greed_index(indicators=None)`** - CNN Fear & Greed Index with selective indicator filtering. Available indicators: fear_and_greed, fear_and_greed_historical, put_call_options, market_volatility_vix, market_volatility_vix_50, junk_bond_demand, safe_haven_demand
- **`get_crypto_fear_greed_index()`** - Current Crypto Fear & Greed Index with value, classification, and timestamp
- **`get_google_trends(keywords, period_days=7)`** - Google Trends relative search interest for market-related keywords. Requires a list of keywords to track (e.g., ["stock market crash", "bull market", "recession", "inflation"]). Returns relative search interest scores that can be used as sentiment indicators.
### Technical Analysis
- **`calculate_technical_indicator(ticker, indicator, period="1y", timeperiod=14, fastperiod=12, slowperiod=26, signalperiod=9, nbdev=2, matype=0, num_results=100)`** - Calculate technical indicators (SMA, EMA, RSI, MACD, BBANDS) with configurable parameters and result limiting. Returns dictionary with price_data and indicator_data as CSV strings. matype values: 0=SMA, 1=EMA, 2=WMA, 3=DEMA, 4=TEMA, 5=TRIMA, 6=KAMA, 7=MAMA, 8=T3. Requires TA-Lib library.
## Usage with MCP Clients
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"investor": {
"command": "uvx",
"args": ["investor-agent"]
}
}
}
```
## Local Testing
For local development and testing, use the included `chat.py` script:
```bash
# Install dev dependencies
uv sync --group dev
# Set up your API key
export OPENAI_API_KEY="your-api-key" # or ANTHROPIC_API_KEY, GEMINI_API_KEY, etc.
# Optional: Set custom model (defaults to openai:gpt-5-mini)
export MODEL_IDENTIFIER="your-preferred-model"
# Run the chat interface
python chat.py
```
For available model providers and identifiers, see the [pydantic-ai documentation](https://ai.pydantic.dev/models/).
## Debugging
```bash
npx @modelcontextprotocol/inspector uvx investor-agent
```
## License
MIT License. See [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "investor-agent",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "agent, broker, finance, investment, mcp, model context protocol, robinhood, trading, wallstreetbets",
"author": null,
"author_email": "Ferdous <ferdous@hey.com>",
"download_url": "https://files.pythonhosted.org/packages/b5/95/bee11fd1f2bc74958735a5b738cb4e3531442048ff4d896a181dd525aa1d/investor_agent-1.5.0.tar.gz",
"platform": null,
"description": "[](https://mseep.ai/app/ferdousbhai-investor-agent)\n\n[](https://archestra.ai/mcp-catalog/ferdousbhai__investor-agent)\n\n# investor-agent: A Financial Analysis MCP Server\n\n## Overview\n\nThe **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, fundamental and technical analysis to deliver:\n\n- **Market Movers:** Top gainers, losers, and most active stocks with support for different market sessions\n- **Ticker Analysis:** Company overview, news, metrics, analyst recommendations, and upgrades/downgrades\n- **Options Data:** Filtered options chains with customizable parameters\n- **Historical Data:** Price trends and earnings history\n- **Financial Statements:** Income, balance sheet, and cash flow statements\n- **Ownership Analysis:** Institutional holders and insider trading activity\n- **Earnings Calendar:** Upcoming earnings announcements with date filtering\n- **Market Sentiment:** CNN Fear & Greed Index, Crypto Fear & Greed Index, and Google Trends sentiment analysis\n- **Technical Analysis:** SMA, EMA, RSI, MACD, BBANDS indicators (optional)\n- **Intraday Data:** 15-minute historical stock bars via Alpaca API (optional)\n\nThe server integrates with [yfinance](https://pypi.org/project/yfinance/) for market data and automatically optimizes data volume for better performance.\n\n## Architecture & Performance\n\n**Robust Caching & Error Handling Strategy:**\n\n1. **`yfinance[nospam]`** \u2192 Built-in smart caching + rate limiting for Yahoo Finance API\n2. **`hishel`** \u2192 HTTP response caching for external APIs (CNN, crypto, earnings data)\n3. **`tenacity`** \u2192 Retry logic with exponential backoff for transient failures\n\nThis multi-layered approach ensures reliable data delivery while respecting API rate limits and minimizing redundant requests.\n\n## Prerequisites\n\n- **Python:** 3.12 or higher\n- **Package Manager:** [uv](https://docs.astral.sh/uv/). Install if needed:\n ```bash\n curl -LsSf https://astral.sh/uv/install.sh | sh\n ```\n\n### Optional Dependencies\n\n- **TA-Lib C Library:** Required for technical indicators. Follow [official installation instructions](https://ta-lib.org/install/).\n- **Alpaca API:** Required for intraday stock data. Get free API keys at [Alpaca Markets](https://alpaca.markets/).\n\n## Installation\n\n### Quick Start\n\n```bash\n# Core features only\nuvx investor-agent\n\n# With technical indicators (requires TA-Lib)\nuvx \"investor-agent[ta]\"\n\n# With Alpaca intraday data (requires Alpaca API keys)\nuvx \"investor-agent[alpaca]\"\n\n# With all optional features\nuvx \"investor-agent[ta,alpaca]\"\n```\n\n## Tools\n\n### Market Data\n- **`get_market_movers(category=\"most-active\", count=25, market_session=\"regular\")`** - Market movers data including top gainers, losers, or most active stocks. Supports different market sessions (regular/pre-market/after-hours) for most-active category. Returns up to 100 stocks with cleaned percentage changes, volume, and market cap data\n- **`get_ticker_data(ticker, max_news=5, max_recommendations=5, max_upgrades=5)`** - Comprehensive ticker report with essential field filtering and configurable limits for news, analyst recommendations, and upgrades/downgrades\n- **`get_options(ticker_symbol, num_options=10, start_date=None, end_date=None, strike_lower=None, strike_upper=None, option_type=None)`** - Options data with advanced filtering by date range (YYYY-MM-DD), strike price bounds, and option type (C=calls, P=puts)\n- **`get_price_history(ticker, period=\"1mo\")`** - Historical OHLCV data with intelligent interval selection: daily intervals for periods \u22641y, monthly intervals for periods \u22652y to optimize data volume\n- **`get_financial_statements(ticker, statement_types=[\"income\"], frequency=\"quarterly\", max_periods=8)`** - Financial statements with parallel fetching support. Returns dict with statement type as key\n- **`get_institutional_holders(ticker, top_n=20)`** - Major institutional and mutual fund holders data\n- **`get_earnings_history(ticker, max_entries=8)`** - Historical earnings data with configurable entry limits\n- **`get_insider_trades(ticker, max_trades=20)`** - Recent insider trading activity with configurable trade limits\n- **`get_nasdaq_earnings_calendar(date=None, limit=100)`** - Upcoming earnings announcements using Nasdaq API (YYYY-MM-DD format, defaults to today).\n- **`fetch_intraday_data(stock, window=200)`** - Fetch 15-minute historical stock bars using Alpaca API. Returns CSV string with timestamp and close price data in EST timezone. Requires `investor-agent[alpaca]` installation and ALPACA_API_KEY/ALPACA_API_SECRET environment variables.\n\n### Market Sentiment\n- **`get_cnn_fear_greed_index(indicators=None)`** - CNN Fear & Greed Index with selective indicator filtering. Available indicators: fear_and_greed, fear_and_greed_historical, put_call_options, market_volatility_vix, market_volatility_vix_50, junk_bond_demand, safe_haven_demand\n- **`get_crypto_fear_greed_index()`** - Current Crypto Fear & Greed Index with value, classification, and timestamp\n- **`get_google_trends(keywords, period_days=7)`** - Google Trends relative search interest for market-related keywords. Requires a list of keywords to track (e.g., [\"stock market crash\", \"bull market\", \"recession\", \"inflation\"]). Returns relative search interest scores that can be used as sentiment indicators.\n\n### Technical Analysis\n- **`calculate_technical_indicator(ticker, indicator, period=\"1y\", timeperiod=14, fastperiod=12, slowperiod=26, signalperiod=9, nbdev=2, matype=0, num_results=100)`** - Calculate technical indicators (SMA, EMA, RSI, MACD, BBANDS) with configurable parameters and result limiting. Returns dictionary with price_data and indicator_data as CSV strings. matype values: 0=SMA, 1=EMA, 2=WMA, 3=DEMA, 4=TEMA, 5=TRIMA, 6=KAMA, 7=MAMA, 8=T3. Requires TA-Lib library.\n\n## Usage with MCP Clients\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"investor\": {\n \"command\": \"uvx\",\n \"args\": [\"investor-agent\"]\n }\n }\n}\n```\n\n## Local Testing\n\nFor local development and testing, use the included `chat.py` script:\n\n```bash\n# Install dev dependencies\nuv sync --group dev\n\n# Set up your API key\nexport OPENAI_API_KEY=\"your-api-key\" # or ANTHROPIC_API_KEY, GEMINI_API_KEY, etc.\n\n# Optional: Set custom model (defaults to openai:gpt-5-mini)\nexport MODEL_IDENTIFIER=\"your-preferred-model\"\n\n# Run the chat interface\npython chat.py\n```\n\nFor available model providers and identifiers, see the [pydantic-ai documentation](https://ai.pydantic.dev/models/).\n\n## Debugging\n\n```bash\nnpx @modelcontextprotocol/inspector uvx investor-agent\n```\n\n## License\n\nMIT License. See [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "A Model Context Protocol server for an investor agent",
"version": "1.5.0",
"project_urls": null,
"split_keywords": [
"agent",
" broker",
" finance",
" investment",
" mcp",
" model context protocol",
" robinhood",
" trading",
" wallstreetbets"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "467848d8489f6c051e67143a69684e5e176329ae3b6a50080e6b82ea464c63fc",
"md5": "f9025775a4f4a1e5495b6d9bcfedcdd8",
"sha256": "a6e6d89dd0559666523ce97146aa4f4f29f1a02190e906d22850ed34c9cd2741"
},
"downloads": -1,
"filename": "investor_agent-1.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f9025775a4f4a1e5495b6d9bcfedcdd8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 14687,
"upload_time": "2025-10-30T07:46:52",
"upload_time_iso_8601": "2025-10-30T07:46:52.507368Z",
"url": "https://files.pythonhosted.org/packages/46/78/48d8489f6c051e67143a69684e5e176329ae3b6a50080e6b82ea464c63fc/investor_agent-1.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b595bee11fd1f2bc74958735a5b738cb4e3531442048ff4d896a181dd525aa1d",
"md5": "8dcc015c4d5f78cda992ec8d84064d28",
"sha256": "e25037184f2598aca21e0a1599a9f65dd5f3ffedb78e151cbc764970115b5a14"
},
"downloads": -1,
"filename": "investor_agent-1.5.0.tar.gz",
"has_sig": false,
"md5_digest": "8dcc015c4d5f78cda992ec8d84064d28",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 126038,
"upload_time": "2025-10-30T07:46:54",
"upload_time_iso_8601": "2025-10-30T07:46:54.977442Z",
"url": "https://files.pythonhosted.org/packages/b5/95/bee11fd1f2bc74958735a5b738cb4e3531442048ff4d896a181dd525aa1d/investor_agent-1.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-30 07:46:54",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "investor-agent"
}
JSON