NSE Data MCP server

An MCP server for NSE equity research. It provides equity-segment securities, Nifty 50 constituents and latest prices, stock and index history, financial results, shareholding patterns, corporate actions, announcements and earnings-call transcripts, bulk/block deals, and short-selling disclosures. Filing documents and detailed XBRL facts can also be downloaded or read.

Install

Python 3.12 or newer is required. With uv:

uv sync

Or with a virtual environment and pip:

python -m venv .venv
source .venv/bin/activate
pip install -e .

Related MCP server: Indian Stock Exchange API2 MCP Server

Run

The default transport is stdio, which is suitable for local MCP clients:

uv run nse-data-mcp

For Streamable HTTP (served at http://localhost:8000/mcp by default):

uv run nse-data-mcp --transport streamable-http

Inspect and connect

Inspect the server interactively with the MCP Inspector:

uv run mcp dev mcp_server.py

Example stdio client configuration:

{
  "mcpServers": {
    "nse-data": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/nse-data-mcp",
        "run",
        "nse-data-mcp"
      ]
    }
  }
}

Replace /absolute/path/to/nse-data-mcp with this repository's absolute path.

Tools

Tabular tools return JSON-safe columns, records, and pagination fields. Use offset and limit when a result is too large for the model context. NSE historical dates use DD-MM-YYYY, and a single source request should span no more than one year.

get_equity_segment_securities reads NSE's equity-segment CSV and returns its original columns and values. It includes all series in that file (such as EQ and BE), with 1,000 rows per page by default. Match NAME OF COMPANY to find the corresponding SYMBOL.

Test

uv sync --extra dev
uv run pytest

Equity research tools

The server also exposes these tools on both stdio and FastMCP/HTTP:

Query and export data

The listing tools require start_date_str and end_date_str in DD-MM-YYYY format. get_financial_results, get_shareholding_patterns, and get_corporate_actions, get_corporate_announcements, and get_earnings_call_transcripts also require an NSE symbol. Shareholding queries accept at most two calendar years, inclusive of the second anniversary. Announcement and transcript queries accept at most one calendar year, inclusive of the first anniversary. For bulk/block deals and short-selling data, symbol is optional; omitting it requests all equities. Dates filter filing/submission dates for financials, ownership and announcements, ex-dates for corporate actions, and trade dates for deals and short-selling disclosures. Reporting-period end dates are separate fields. Timestamps without an explicit source timezone are interpreted as India time (+05:30).

Requests are split into nonoverlapping 31-day windows. Financial results use the legacy feed for filing dates before 01-04-2025 and Integrated Filing from that date; results retain source_feed. The financial tool also follows Integrated Filing's upstream pagination. Exact duplicates are removed; distinct revisions and buyer/seller disclosures are retained. Results are sorted by date descending. Client pagination is applied after retrieval and filtering; requesting the next page fetches the source again, so recently changing data can shift page boundaries. Narrow symbol/date filters reduce the request volume.

get_short_selling_data returns the reported short-sold share quantity from NSE's short-selling archive for each security and trade date. This measures short-selling activity, not an outstanding short position. It has no client, trade side, or price fields.

All listings and XBRL facts support offset, limit (1–5000), and output_format="json" or "csv". CSV output contains the requested page plus pagination metadata; nested fields such as raw and documents are JSON inside CSV cells. Follow next_offset to export further pages. Missing numeric values remain null, distinct from reported zeros. Original source records and URLs are retained for verification.

Example MCP tool arguments:

{
  "tool": "get_financial_results",
  "arguments": {
    "symbol": "INFY",
    "start_date_str": "01-07-2026",
    "end_date_str": "31-07-2026",
    "basis": "consolidated",
    "period": "all",
    "limit": 100
  }
}

basis accepts all, consolidated, or standalone. period accepts all (default), Quarterly, Half-Yearly, Annual, or Others. Period-specific filters are available only for date ranges entirely before 01-04-2025. Integrated listing rows do not classify their reporting period, so requests touching the integrated era must use period="all". Use XBRL contexts to select the actual accounting duration. For legacy dates, period="all" queries all four period types because NSE's default feed does not include them all.

Detailed financial and ownership data

Listings expose document URLs; they do not flatten entire financial statements. Call get_filing_facts with a document whose kind is xbrl to obtain revenue, profit, EPS, balance-sheet/cash-flow or ownership/pledge facts where reported. For example, use concept="Revenue" or concept="Pledged", or omit concept to retrieve every fact. The filter searches taxonomy concept names, not synonyms.

Each fact retains its exact string value, qualified concept, entity, period, unit definition, dimensions, decimals/precision and explicit nil flag. This preserves financial precision and avoids combining different periods, units, segments or shareholders. Ratios, price adjustments and cross-company accounting normalisation are not calculated. Use XML xbrl links, not rendered ixbrl HTML, for fact extraction. Legacy HTML results can instead be read with get_corporate_document.

Earnings-call transcripts and documents

1. Call get_earnings_call_transcripts with a symbol and filing-date range (or get_corporate_announcements with document_type="earnings_call_transcript").

2. Pass a returned attachment URL to get_corporate_document.

3. Follow its pagination.next_offset to read the remaining text.

Transcript discovery matches descriptions and filenames, including common spelling variants; it does not inspect every PDF. Generic call invitations and audio announcements without transcript references are excluded. Metadata can be ambiguous, so discovery is not guaranteed complete. Some filings contain only a cover letter linking to an issuer-hosted transcript; extracted document links are returned but external issuer websites are not downloaded by this tool.

For document text, offset/limit count characters (default limit 20000; maximum 100000). PDF text includes page markers and reports pages without text. Scanned documents require OCR, which is not included.

For original-file downloads, set output_format="base64"; offsets and limits then count original bytes. Decode each chunk separately and concatenate the bytes in order. size_bytes and sha256 allow verification of the assembled file. Downloads are capped at 25 MiB; PDF text extraction at 500 pages. The server returns content without writing files. Only HTTPS NSE and archive hosts are accepted, including after redirects.

Testing the research features

uv run pytest

The default suite uses small captured NSE responses, generated PDFs and HTTP mocks. It covers all new tools through both MCP implementations, CSV/JSON pagination, both financial feeds, source pagination, revisions, transcript classification, XBRL context/units, malformed responses, retries and bounded attachment downloads.

Live tests are opt-in, require network access to NSE, and use known historical filings and deals. They exercise old and current financial results, detailed financial/ownership XBRL, corporate actions, an actual transcript PDF, and both deal types:

NSE_LIVE_TESTS=1 uv run pytest tests/test_live_nse.py -v

For a diagnostic run in environments where only system curl has network access, set NSE_LIVE_TRANSPORT=curl as well. This replaces the transport only in the live tests; it does not add a curl dependency or fallback to the production server.

NSE endpoints may change or return access challenges. HTTP failures, unexpected payloads and incomplete upstream pagination raise errors instead of returning a misleading empty dataset. Live tests fail visibly if upstream access is blocked.