Equity Analyzer MCP Node

This Model Context Protocol (MCP) server furnishes robust capabilities for querying and filtering publicly traded securities using data aggregated from Yahoo Finance. It empowers large language models (LLMs) to perform complex investment analysis by applying diverse constraints spanning technical momentum, corporate fundamentals, and options market characteristics, alongside integrated portfolio list management and result persistence.

Core Capabilities

Securities Screening Engine

• Technical Momentum Evaluation
• Price level and trading volume constraints
• Simple Moving Average (SMA) checks (20-period, 50-period, 200-period)
• Relative Strength Index (RSI) boundaries
• Average True Range (ATR) volatility metrics
• Short-term and intermediate-term price trajectory assessment (1-day, 5-day, 20-day percentage shifts)

• Deviation calculation relative to key SMAs

• Fundamental Health Assessment

• Equity valuation thresholds (Market Cap)
• Price-to-Earnings (P/E) multiple constraints
• Shareholder return metrics (Dividend Yield)
• Top-line expansion measurements (Revenue Growth)

• Exchange Traded Fund (ETF) specific attributes (Assets Under Management, Fee Structure)

• Derivatives Market Analysis (Options)

• Implied Volatility (IV) range specification
• Open interest and daily contract turnover volume
• Sentiment proxy (Put/Call ratio evaluation)
• Liquidity assessment (Bid-Ask spread evaluation)
• Proximity assessment relative to scheduled corporate earnings events

Portfolio & Data Utilities

• Creation and maintenance of user-defined security lists (Watchlists)
• Persistent storage mechanism for computed screening outcomes
• Predefined grouping of assets based on asset size:
• 'mega_cap': Valuation exceeding $200 Billion
• 'large_cap': Valuation between $10B and $200B
• 'mid_cap': Valuation between $2B and $10B
• 'small_cap': Valuation between $300 Million and $2B
• 'micro_cap': Valuation below $300 Million
• 'etf': Instrument type indicator

Setup Procedure

bash

Install necessary packages

pip install -r requirements.txt

Obtain repository files

git clone https://github.com/twolven/mcp-stockscreen.git cd mcp-stockscreen

Operational Integration

1. Configure your Claude environment: In the claude-desktop-config.json file, augment the mcpServers configuration block:

{ "mcpServers": { "equityanalyzer": { "command": "python", "args": ["path/to/stockscreen.py"] } } }

Ensure 'path/to/stockscreen.py' points to the exact location of the executable script.

Accessible Operations (Tools)

Accessible Operations (Tools)

1. run_stock_screen

Technical Parameter Schema

python { "screen_type": "technical", "criteria": { "min_price": float, # Floor for per-share price "max_price": float, # Ceiling for per-share price "min_volume": int, # Minimum average daily trading volume "above_sma_200": bool, # Boolean: Price status relative to 200-day Simple MA "above_sma_50": bool, # Boolean: Price status relative to 50-day Simple MA "min_rsi": float, # Lower threshold for RSI "max_rsi": float, # Upper threshold for RSI "max_atr_pct": float, # Maximum volatility expressed as % of current price "category": str # Optional: Predefined market cap segment tag }, "watchlist": str, # Optional: Identifier of a pre-loaded symbol list to analyze "save_result": str # Optional: Tag to assign to the output dataset }

Fundamental Parameter Schema

python { "screen_type": "fundamental", "criteria": { "min_market_cap": float, # Lower bound for total company valuation "min_pe": float, # Minimum acceptable P/E ratio "max_pe": float, # Maximum acceptable P/E ratio "min_dividend": float, # Minimum required dividend yield (in percent) "min_revenue_growth": float, # Minimum required annualized revenue growth rate "category": str, # Optional: Market capitalization classification

    "min_aum": float,                # For ETFs: Minimum total assets managed
    "max_expense_ratio": float,      # For ETFs: Maximum permissible expense ratio
    "min_volume": float              # For ETFs: Minimum average trading volume
},
"watchlist": str,
"save_result": str

}

Options Parameter Schema

python { "screen_type": "options", "criteria": { "min_iv": float, # Minimum acceptable Implied Volatility (%) "max_iv": float, # Maximum acceptable Implied Volatility (%) "min_option_volume": int, # Minimum contract volume across all options series "min_put_call_ratio": float, # Minimum implied bearish/bullish sentiment indicator "max_spread": float, # Maximum allowable bid-ask spread percentage "min_days_to_earnings": int, # Lower bound on days remaining until next earnings release "max_days_to_earnings": int, # Upper bound on days remaining until next earnings release "category": str # Optional: Market capitalization segment tag }, "watchlist": str, "save_result": str }

News Analysis Parameter Schema

python { "screen_type": "news", "criteria": { "keywords": List[str], # Required terms to find within headlines/summaries "exclude_keywords": List[str], # Terms that disqualify a news item "min_days": int, # Oldest acceptable news item age (days) "max_days": int, # Newest acceptable news item age (days) "management_changes": bool, # Flag to restrict results to corporate leadership shifts "require_all_keywords": bool, # Logical AND operation for keyword matching "category": str # Optional: Market capitalization segment tag }, "watchlist": str, "save_result": str }

Composite Parameter Schema

python { "screen_type": "custom", "criteria": { "category": str, # Optional: Market cap classification tag "technical": { # Embedding of any parameters from the technical schema above }, "fundamental": { # Embedding of any parameters from the fundamental schema above }, "options": { # Embedding of any parameters from the options schema above }, "news": { # Embedding of any parameters from the news schema above } }, "watchlist": str, "save_result": str }

Classification Tags Reference

Valid security class tags for filtering: - "mega_cap": Valuation > $200 Billion - "large_cap": $10 Billion to $200 Billion range - "mid_cap": $2 Billion to $10 Billion range - "small_cap": $300 Million to $2 Billion range - "micro_cap": Valuation < $300 Million - "etf": Exchange Traded Product designation

1. manage_watchlist python { "action": str, # Mandatory: Operation type ("create", "update", "delete", "get") "name": str, # Mandatory: Identifier for the list (1-50 chars, alphanumeric + hyphen/underscore) "symbols": List[str] # Mandatory for creation/modification: List of security tickers }

2. get_screening_result python { "name": str # Mandatory: Identifier referencing the previously saved outcome }

Output Structures

Technical Screening Output Model

python { "screen_type": "technical", "criteria": dict, # Echo of the input criteria configuration "matches": int, # Count of securities fulfilling all requirements "results": [ # List of qualifying securities { "symbol": str, "price": float, "volume": float, "rsi": float, "sma_20": float, "sma_50": float, "sma_200": float, "atr": float, "atr_pct": float, "price_changes": { "1d": float, # Daily percentage movement "5d": float, # 5-day cumulative percentage movement "20d": float # 20-day cumulative percentage movement }, "ma_distances": { "pct_from_20sma": float, "pct_from_50sma": float, "pct_from_200sma": float } } ], "rejected": [ # List of securities evaluated but excluded { "symbol": str, "rejection_reasons": List[str] } ], "timestamp": str }

Operational Guide for Claude

"The integrated equity-analyzer-service provides sophisticated methods for filtering public equities. You may execute three primary operations:

1. Execute a comprehensive equity scan using modes:
2. Technical: Focus on momentum indicators (MA convergence, RSI, volatility)
3. Fundamental: Focus on balance sheet/valuation metrics (Market Cap, P/E, growth)
4. Options: Focus on derivatives market signals (IV, volume, earnings risk)

5. Custom: Blend parameters from any of the above screening domains

6. Administer symbol lists (watchlists):

7. Initialize, modify, or discard custom security groupings.

8. Retrieve the current contents of any watchlist.

9. Access historical analysis records:

10. Load and inspect the outcomes of previously executed screening jobs.
11. Review the symbols that passed and the criteria they satisfied.

All tool interactions incorporate robust error validation, retrieval of fresh market data where applicable, and detailed structural outputs."

Software Prerequisites

• Python interpreter version 3.12 or newer
• MCP Framework Implementation
• yfinance library for data acquisition
• pandas for data manipulation
• numpy for numerical operations
• asyncio for asynchronous handling

Known Limitations

• All financial information is subject to the latency and policy restrictions imposed by the Yahoo Finance data feeds.
• Excessive query rates may trigger temporary service throttling from Yahoo Finance.
• Options data availability is contingent upon active market trading hours.
• Certain detailed financial metrics might occasionally be missing or stale.

Development Contributions

We encourage external development! Please submit proposed enhancements via a Pull Request.

Licensing

This software is distributed under the terms of the MIT License. Consult the [LICENSE] file for specifics.

Creator

Todd Wolven - (https://github.com/twolven)

Credits

• Framework foundation based on the Model Context Protocol (MCP) by Anthropic
• Primary data source: Yahoo Finance
• Designed for seamless integration with Anthropic's Claude models.

WIKIPEDIA: XMLHttpRequest (XHR) is an API in the form of a JavaScript object whose methods transmit HTTP requests from a web browser to a web server. The methods allow a browser-based application to send requests to the server after page loading is complete, and receive information back. XMLHttpRequest is a component of Ajax programming. Prior to Ajax, hyperlinks and form submissions were the primary mechanisms for interacting with the server, often replacing the current page with another one.

== History == The concept behind XMLHttpRequest was conceived in 2000 by the developers of Microsoft Outlook. The concept was then implemented within the Internet Explorer 5 browser (1999). However, the original syntax did not use the XMLHttpRequest identifier. Instead, the developers used the identifiers ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (2006), all browsers support the XMLHttpRequest identifier. The XMLHttpRequest identifier is now the de facto standard in all the major browsers, including Mozilla's Gecko layout engine (2002), Safari 1.2 (2004) and Opera 8.0 (2005).

=== Standards === The World Wide Web Consortium (W3C) published a Working Draft specification for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C published the Working Draft Level 2 specification. Level 2 added methods to monitor event progress, allow cross-site requests, and handle byte streams. At the end of 2011, the Level 2 specification was absorbed into the original specification. At the end of 2012, the WHATWG took over development and maintains a living document using Web IDL.

== Usage == Generally, sending a request with XMLHttpRequest has several programming steps.

Create an XMLHttpRequest object by calling a constructor: Call the "open" method to specify the request type, identify the relevant resource, and select synchronous or asynchronous operation: For an asynchronous request, set a listener that will be notified when the request's state changes: Initiate the request by calling the "send" method: Respond to state changes in the event listener. If the server sends response data, by default it is captured in the "responseText" property. When the object stops processing the response, it changes to state 4, the "done" state. Aside from these general steps, XMLHttpRequest has many options to control how the request is sent and how the response is processed. Custom header fields can be added to the request to indicate how the server should fulfill it, and data can be uploaded to the server by providing it in the "send" call. The response can be parsed from the JSON format into a readily usable JavaScript object, or processed gradually as it arrives rather than waiting for the entire text. The request can be aborted prematurely or set to fail if not completed in a specified amount of time.

== Cross-domain requests ==

In the early development of the World Wide Web, it was found possible to brea