SFinance MCP Server

A Model Context Protocol (MCP) server that provides access to Indian stock market data. Built on top of the SFinance package.

Supports both stdio (Claude Desktop) and HTTP transports.

Prerequisites

• Python 3.11.6 or higher

• uv package manager

• Google Chrome browser

• Screener.in account

Related MCP server: Indian Stock Exchange MCP Server

Installation

1. Clone and setup

   git clone https://github.com/shivakharbanda/sfinance-mcp-server.git
   cd sfinance-mcp-server
   uv sync

2. Environment variables Create a .env file in the project root:

   SCREENER_EMAIL=your-email@example.com
   SCREENER_PASSWORD=YourPassword123
   CHROME_PATH=C:\Program Files\Google\Chrome\Application\chrome.exe
   SCREENER_URL=https://www.screener.in/

Running the Server

HTTP mode (remote / API access)

uv run python sfinance_server.py --transport http

The server starts at http://0.0.0.0:8000/mcp.

Custom host/port:

uv run python sfinance_server.py --transport http --host 127.0.0.1 --port 9000

Or via environment variables:

TRANSPORT=http HOST=0.0.0.0 PORT=8000 uv run python sfinance_server.py

Health check endpoint: GET http://localhost:8000/health

Stdio mode (Claude Desktop)

uv run python sfinance_server.py

Claude Desktop Configuration

Option 1: uv run (Recommended)

Windows:

{
  "mcpServers": {
    "sfinance": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "C:\\path\\to\\sfinance-mcp-server",
        "python", "sfinance_server.py"
      ],
      "env": {
        "SCREENER_EMAIL": "your-email@example.com",
        "SCREENER_PASSWORD": "YourPassword123",
        "CHROME_PATH": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
        "SCREENER_URL": "https://www.screener.in/"
      }
    }
  }
}

macOS/Linux:

{
  "mcpServers": {
    "sfinance": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/sfinance-mcp-server",
        "python", "sfinance_server.py"
      ],
      "env": {
        "SCREENER_EMAIL": "your-email@example.com",
        "SCREENER_PASSWORD": "YourPassword123",
        "CHROME_PATH": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
        "SCREENER_URL": "https://www.screener.in/"
      }
    }
  }
}

Option 2: HTTP transport (connect to a running server)

If you already have the server running in HTTP mode, point Claude Desktop at it:

{
  "mcpServers": {
    "sfinance": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Configuration File Locations

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Features

• Stock Analysis: Company overview, financial statements, quarterly results, shareholding patterns, peer comparison

• Document Access (login required): Announcements, annual reports, credit ratings, concall transcripts/PPTs

• Document Download (login required): Batch download any document type to a local folder

• Stock Screening (login required): Custom queries with financial parameters and pre-built templates

• Indian Market Focus: NSE/BSE listed companies via screener.in

Available Tools

Stock Data

Documents (login required)

Screening (login required)

Utilities

Usage Examples

Get overview for RELIANCE
Get income statement for TCS
Get concalls for INFY
Download the last 3 annual reports for HDFCBANK to C:\Downloads\HDFCBANK
Screen stocks with Piotroski score > 7 AND Return on equity > 15
Find value stocks with Price to Earning < 15 AND Dividend yield > 3

Prompt Templates

• High Quality Stocks - Strong fundamentals (Piotroski, ROE, P/E)

• Value Stocks - Undervalued opportunities (P/E, P/B, dividend yield)

• Growth Stocks - High-growth companies (sales/profit growth, ROE)

• Custom Screener - Build your own criteria

Dependencies

• sfinance - Core data library

• fastmcp - MCP server framework (stdio + HTTP)

• pandas - Data handling

• python-dotenv - Environment variables

License

Apache License 2.0

Disclaimer

For educational purposes only. Always verify financial data from official sources before making investment decisions.

Legal Notice

Users are solely responsible for ensuring that their use of this software complies with the terms of service of any website they access.

This project is not affiliated with, endorsed by, or sponsored by Screener.in, Mittal Analytics Private Limited, or any other third-party data provider.