screener_mcp

screener_mcp

0
financeresearch_and_datadeveloper_tools

The Screener.in MCP Server project provides a Model Context Protocol server that allows large language models to interact with Indian stock market data. It offers tools for company data analysis using web scraping methods and focuses on integrating with Claude Desktop for enhanced data interaction.

Screener.in MCP Server

This project provides a Model Context Protocol (MCP) server that allows Large Language Models (LLMs) like Claude to interact with data from Screener.in for Indian stock market analysis.

It uses FastMCP to define tools, resources, and prompts for fetching company overviews, financial ratios, and searching for companies on Screener.in.

Disclaimer: This server relies on web scraping Screener.in.

  • Fragility: Web scraping can break if Screener.in changes its website structure.
  • Rate Limiting/Blocking: Screener.in might block or rate-limit your IP if you make too many requests too quickly. Use responsibly and consider adding delays if you encounter issues.
  • Terms of Service: Always review and comply with Screener.in's terms of service regarding automated data extraction. This project is for educational and personal use demonstration.

Features

The MCP server provides the following capabilities:

  • Tools:
    • get_company_overview: Fetches an overview of a company using its stock symbol (e.g., "RELIANCE").
    • get_peer_comparision: Fetches peer comparions for a company.
    • search_companies: Searches Screener.in for companies based on a query string.
  • Resources (via Resource Templates):
    • screener://company/{company_symbol}/overview_data: Provides a company's overview data.
    • screener://company/{company_symbol}/company_peer_comparision_resource: Provides a company's peer comparision as a resource.
  • Prompts:
    • suggest_company_analysis: Generates a prompt for an LLM to analyze a company using the available resources.

Prerequisites

  • Python 3.10+
  • uv: Recommended for Python environment and package management.
  • Claude Desktop App (if you intend to use it with Claude Desktop).

Setup and Installation

  1. Clone the repository (if you haven't already):

    git clone < link of this repo >
cd screener_mcp

  2. Create a virtual environment and install dependencies: Using uv:

    uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

    This installs the project in editable mode and all its dependencies as defined in pyproject.toml.

  3. (Optional) Create a .env file: If you plan to extend this server to use API keys or other sensitive configurations, create a .env file in the project root:

    # Example .env content (not currently used by this server)
# SOME_API_KEY="your_api_key_here"

Running the Server

For Local Testing / Direct Invocation

You can run the server directly for local testing or if another application will manage its lifecycle (e.g., via STDIO).

  • Using the defined script entry point (after installation):

    screener-server

    This will run the server using src/screener_mcp_server/server.py and its run_server_cli function, which defaults to STDIO transport.

  • Using fastmcp run: This is useful for development as fastmcp handles module pathing.

    fastmcp run src/screener_mcp_server/server.py:mcp

    (Assuming your FastMCP instance in server.py is named mcp).

  • Directly with Python:

    python src/screener_mcp_server/server.py

Integrating with Claude Desktop App

To use this server as a tool within the Claude Desktop application:

  1. Navigate to the root directory of this project (screener_mcp/) in your terminal.

  2. Run the fastmcp install command:

    fastmcp install src/screener_mcp_server/server.py:mcp --name "Screener.in Tool" --with-editable .
    • src/screener_mcp_server/server.py:mcp: Points to your server file and the FastMCP instance.
    • --name "Screener.in Tool": The display name in Claude Desktop.
    • --with-editable .: Ensures Claude Desktop uses your local project code and installs its dependencies.

  3. Restart Claude Desktop App.

  4. Enable the Tool: In Claude Desktop, find "Screener.in Tool" in the tools/MCP servers section and enable it for your chat.

  5. Interact with Claude: You can now ask Claude to use the tool, for example:

    • "Using the Screener.in Tool, get me an overview of RELIANCE."
    • "Search for 'Tata Motors' on Screener.in."
    • "Fetch financial ratios for INFY using the Screener.in tool."

Development

The core logic for fetching data from Screener.in resides in src/screener_mcp_server/screener_utils.py. This file currently contains placeholder functions. Wweb scraping logic is implemented using httpx and BeautifulSoup4 libraries.

Key files:

  • pyproject.toml: Project metadata and dependencies.
  • src/screener_mcp_server/server.py: Defines the FastMCP server, tools, resources, and prompts.
  • src/screener_mcp_server/screener_utils.py: Contains helper functions for web scraping Screener.in.

Implementing Web Scraping

When implementing screener_utils.py:

  1. Use httpx.AsyncClient for making HTTP requests to Screener.in.
  2. Inspect the HTML structure of Screener.in pages to identify the correct CSS selectors or XPath expressions for the data you need.
  3. Use BeautifulSoup4 or a similar library to parse the HTML and extract data.
  4. Implement robust error handling for network issues, HTTP errors, and changes in website structure.
  5. Consider adding delays between requests if you plan to fetch data frequently, to avoid overloading Screener.in's servers.

Future Enhancements (Ideas)

  • Implement caching for scraped data to reduce redundant requests.
  • Add more specific tools/resources (e.g., for peer comparison, charts, quarterly results).
  • Improve error handling and reporting.
  • Add configurable delays for scraping.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.