# India Finance MCP (`vamppog/india-finance-mcp`) Actor MCP server for Indian financial data. Get real-time mutual fund NAVs from AMFI (47,000+ schemes), validate GSTIN numbers with checksum verification, and more. Built for AI agents (Claude, ChatGPT, Cursor) via MCP protocol. REST API also available. Stock quotes coming in v1.1. - **URL**: https://apify.com/vamppog/india-finance-mcp.md - **Developed by:** [Tushar](https://apify.com/vamppog) (community) - **Categories:** AI, Developer tools, MCP servers - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README [![Apify Actor](https://img.shields.io/badge/Apify-Store-00C896?logo=apify)](https://apify.com/vamppog/india-finance-mcp) [![Cloudflare Workers](https://img.shields.io/badge/CF%20Workers-Live-F38020?logo=cloudflare)](https://india-finance-mcp.vamp-fa0.workers.dev) ## India Finance MCP A Model Context Protocol (MCP) server exposing **Indian financial data** to LLMs and agents, with a parallel REST API for non-MCP consumers. Single TypeScript codebase, two deployment targets: - **MCP server** (FastMCP, Node) — deployed as an [Apify Actor](https://apify.com/vamppog/india-finance-mcp). Plug it into Claude Desktop, Cursor, or any MCP-compatible client. - **REST mirror** (Hono on Cloudflare Workers) — for HTTP clients, monetizable via RapidAPI. Live as of 2026-05-04. | Target | URL | Transports | |--------|-----|------------| | Apify Actor | `https://apify.com/vamppog/india-finance-mcp` | MCP (Streamable HTTP) at `/mcp` via FastMCP | | Cloudflare Workers | `https://india-finance-mcp.vamp-fa0.workers.dev` | MCP (JSON-RPC) at `POST /mcp` **+** REST at `/api/*` | --- ### What it does | Tool | Purpose | Source | Auth needed | |------|---------|--------|-------------| | `get_mutual_fund_nav` | Look up the latest NAV for any Indian mutual fund by AMFI scheme code or free-text scheme name. | [AMFI](https://www.amfiindia.com/spages/NAVAll.txt) — daily refresh | None | | `validate_gstin` | Structural + checksum validation of a 15-character GSTIN. Parses out state, embedded PAN, entity code. | Offline (mod-36 checksum) | None | Planned for v1.1: | Tool | Purpose | Source | |------|---------|--------| | `get_stock_quote` | Latest quote for NSE/BSE-listed equities. | Yahoo Finance proxy (`RELIANCE.NS`-style symbols) | --- ### Quickstart #### As an MCP client (Claude Desktop, Cursor, etc.) You have three options: **Option A — Cloudflare Workers (always-on, no Apify standby needed):** ```` POST https://india-finance-mcp.vamp-fa0.workers.dev/mcp ```` Speaks MCP Streamable HTTP / JSON-RPC. Works with any MCP client that supports HTTP transport. **Option B — Apify Actor (FastMCP-backed):** Once the actor's standby mode is enabled in the Apify console, point your MCP client at the actor's MCP endpoint at `/mcp`. **Option C — local stdio:** ```bash git clone cd "Indian finance MCP" npm install npm run dev:mcp ## stdio transport for local MCP clients ```` For an interactive UI, use the FastMCP inspector: ```bash npm run inspect ## opens fastmcp dev UI ``` #### As an MCP client over plain HTTP (curl) ```bash ## initialize curl -X POST https://india-finance-mcp.vamp-fa0.workers.dev/mcp \ -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' ## tools/list curl -X POST https://india-finance-mcp.vamp-fa0.workers.dev/mcp \ -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' ## tools/call curl -X POST https://india-finance-mcp.vamp-fa0.workers.dev/mcp \ -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"validate_gstin","arguments":{"gstin":"27AAPFU0939F1ZV"}}}' ``` #### As a REST client ```bash ## Mutual fund NAV by AMFI scheme code curl 'https://india-finance-mcp.vamp-fa0.workers.dev/api/mutual-fund/nav?code=122639' ## Free-text scheme name search curl 'https://india-finance-mcp.vamp-fa0.workers.dev/api/mutual-fund/nav?q=parag+parikh+flexi+cap+direct&limit=5' ## GSTIN validation curl 'https://india-finance-mcp.vamp-fa0.workers.dev/api/gstin/validate?gstin=27AAPFU0939F1ZV' ``` Sample response (NAV): ```json { "query": "122639", "matches": [ { "schemeCode": "122639", "isinGrowth": "INF879O01027", "isinReinvestment": null, "schemeName": "Parag Parikh Flexi Cap Fund - Direct Plan - Growth", "nav": 91.2902, "date": "30-Apr-2026", "category": "Open Ended Schemes(Equity Scheme - Flexi Cap Fund)", "amc": "PPFAS Mutual Fund" } ], "asOf": "30-Apr-2026", "source": "amfi" } ``` Sample response (GSTIN): ```json { "gstin": "27AAPFU0939F1ZV", "valid": true, "errors": [], "parts": { "stateCode": "27", "stateName": "Maharashtra", "pan": "AAPFU0939F", "entityCode": "1", "defaultLetter": "Z", "checksum": "V" } } ``` *** ### Architecture ``` src/ ├── core/ ## Pure logic + I/O. Workers-safe. No fastmcp/hono imports. │ ├── amfi.ts ## Fetch + parse + 1h TTL cache + search for AMFI NAV file │ ├── gstin.ts ## Mod-36 checksum, state-code table, structural checks │ └── types.ts ## Shared record/result types ├── tools/ ## MCP-tool contracts: zod schema + execute() + _TOOL const │ ├── mutual-fund-nav.ts │ └── validate-gstin.ts ├── mcp/ │ └── index.ts ## FastMCP entry — addTool(...) per tool, stdio or http-stream └── rest/ ├── app.ts ## Hono app — REST routes + POST /mcp (JSON-RPC) ├── mcp-handler.ts ## Workers-safe MCP JSON-RPC dispatcher (no fastmcp) ├── worker.ts ## Cloudflare Workers entry: { fetch: app.fetch } └── node.ts ## Local-dev entry via @hono/node-server ``` #### How a tool is added 1. **Write the logic in `src/core/`** — pure functions and any caching. Keep this layer dependency-free; it has to run on both Node (Apify) and the Workers runtime. 2. **Define the contract in `src/tools/`** — export a zod schema, an `execute` function, and a `*_TOOL` const that bundles them with the tool's MCP name + description. This contract is reused by both entries. 3. **Wire it into MCP** in `src/mcp/index.ts` via `server.addTool({...})`. Tool results must be returned as a JSON string. 4. **Wire it into REST** in `src/rest/app.ts` — add a route, parse query params with `.safeParse`, call `execute`, return `c.json(...)`. This is the rule the codebase optimizes for: **one logic implementation, one contract, two transports.** #### Transport detection (Apify / FastMCP entry) `src/mcp/index.ts` chooses transport at startup: | Trigger | Transport | Use case | |---------|-----------|----------| | `APIFY_CONTAINER_PORT` set | `httpStream` on that port | Apify Actor runtime | | `FASTMCP_TRANSPORT=http-stream` | `httpStream` on `PORT` (default 8080) | Self-hosted HTTP | | Neither | `stdio` | Claude Desktop, local CLI, FastMCP inspector | #### MCP on Cloudflare Workers (no FastMCP) The Workers deploy serves MCP via a hand-rolled JSON-RPC handler in `src/rest/mcp-handler.ts` because FastMCP pulls in Node-only deps that don't bundle for Workers. The handler implements `initialize`, `notifications/initialized` (acked with HTTP 202), `ping`, `tools/list`, and `tools/call`. Tool input schemas are emitted from the same zod schemas used by the FastMCP entry, via `zod-to-json-schema`. Both entries therefore expose identical tool surface — only the framework underneath differs. Stateless: no session id, no SSE stream. Each POST is one JSON-RPC request and returns one JSON response (or 202 for notifications). #### Caching `getNavRecords()` in `core/amfi.ts` memoizes the parsed AMFI file with a **1-hour in-memory TTL** plus an inflight request de-dupe (concurrent calls share a single fetch promise). - On Node/Apify the cache lives across requests for the lifetime of the process. - On Cloudflare Workers it lives **per isolate** — cold isolates re-fetch. For cross-isolate caching, bind a KV namespace in `wrangler.toml` (a commented stub is already there) and short-circuit before the AMFI fetch. AMFI publishes the daily NAV file once per business day around 9–11 PM IST. #### Module-resolution gotcha `tsconfig.json` uses `moduleResolution: "Bundler"` with `verbatimModuleSyntax: true`. Imports between `src/` files **must** end in `.js` even though the source is `.ts`: ```ts import { getNavRecords } from "../core/amfi.js"; // ✅ import { getNavRecords } from "../core/amfi"; // ❌ build will fail ``` Both `tsc` and Wrangler/esbuild resolve this correctly. #### Workers compatibility constraint `src/rest/worker.ts` and its transitive imports must be Workers-safe: - ✅ Global `fetch`, pure logic, Hono. - ❌ `process.env`, `@hono/node-server`, anything from `src/mcp/`, anything from `fastmcp`. FastMCP pulls in Node-only deps that won't bundle for Workers. The current import graph through `worker.ts → app.ts → tools/* → core/{amfi,gstin}.ts` honors this; keep it that way. *** ### Development #### Setup ```bash npm install ## ~225 packages ``` #### Common commands ```bash npm test ## all vitest tests npx vitest run tests/gstin.test.ts -t "checksum" ## single test by file + name npx vitest ## watch mode npx tsc --noEmit ## typecheck only npm run dev:mcp ## tsx watch — stdio MCP server npm run inspect ## fastmcp dev — interactive MCP inspector UI npm run dev:rest ## tsx watch — Hono on http://localhost:3000 npm run cf:dev ## wrangler dev — Workers runtime on http://localhost:8787 npx tsx scripts/smoke.ts ## end-to-end smoke test against live AMFI ``` #### Building The `dist/` build is **only needed for the Apify Docker image**. `Dockerfile` runs `tsc` in the builder stage. Wrangler bundles `src/rest/worker.ts` directly — no pre-build required for CF Workers. ```bash npm run build ## tsc → dist/ ``` #### Testing approach - `tests/amfi.test.ts` parses a fixture string covering category headers, AMC headers, blank `;;;;;` rows, and `N.A.` NAV rows. Extend the fixture rather than mocking the fetch. - `tests/gstin.test.ts` covers valid GSTINs, length/format/state/PAN errors, and bad-checksum cases. Bad-state and bad-PAN tests recompute a valid checksum first to **isolate the error under test** — important when adding new validation rules. - `_resetCacheForTesting()` is exported from `core/amfi.ts` if a future test needs to re-exercise the fetch path. *** ### Deployment #### Apify (MCP server) ```bash npm install -g apify-cli apify login apify push --wait-for-finish 600 ``` Configuration lives in `.actor/actor.json`. The `webServerMcpPath` field tells Apify to route MCP traffic to `/mcp`. The `Dockerfile` is multi-stage (Alpine, build → runtime) and starts the server with `FASTMCP_TRANSPORT=http-stream` and `FASTMCP_STATELESS=true`. After the build succeeds, **enable Standby mode** in the Apify console to make the MCP endpoint addressable. That step is console-only — no CLI equivalent. #### Cloudflare Workers (REST mirror) ```bash npx wrangler login npx wrangler deploy ``` `wrangler.toml` pins `account_id` (set per-developer; default in this repo is the Vamp account). To use a different account, override with `CLOUDFLARE_ACCOUNT_ID` or edit the file. The build is a single bundle (~190 KiB / ~38 KiB gzipped). No KV bindings yet — adding cross-isolate caching is the obvious next infra change. *** ### Project structure ``` . ├── .actor/ ## Apify actor metadata (actor.json, input_schema.json) ├── src/ ## See architecture diagram above ├── tests/ ## vitest suites ├── scripts/smoke.ts ## End-to-end smoke test ├── Dockerfile ## Multi-stage build for Apify ├── wrangler.toml ## Cloudflare Workers config ├── tsconfig.json ## Bundler-mode + verbatimModuleSyntax ├── vitest.config.ts └── package.json ``` *** ### Data sources & legal notes - **AMFI NAV file** (`https://www.amfiindia.com/spages/NAVAll.txt`) — public, no auth, attribution recommended. The `source: "amfi"` field is included in every NAV response. - **GSTIN validation** — entirely offline. The mod-36 checksum is the public algorithm published by GSTN. This tool does **not** call the GSTN portal and does **not** confirm whether a GSTIN is currently active or registered to any specific entity. It only confirms that the string is structurally well-formed. - **Stock quotes** (planned) — Yahoo Finance has no official free terms-of-use; use at your own risk and consider swapping to a paid provider before commercializing the stock-quote tool. *** ### Roadmap - \[x] v0.1 — `get_mutual_fund_nav`, `validate_gstin`, deployed to Apify + CF Workers - \[ ] v1.1 — `get_stock_quote` (Yahoo Finance proxy, NSE + BSE) - \[ ] v1.2 — `get_market_summary` (indices snapshot) - \[ ] Infra — KV-backed NAV cache for cross-isolate persistence on Workers - \[x] Listings — Apify Store - \[ ] Listings — Smithery, Glama, mcp.so, PulseMCP, official MCP registry *** ### License MIT # Actor input Schema ## Actor input object example ```json {} ``` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("vamppog/india-finance-mcp").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("vamppog/india-finance-mcp").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call vamppog/india-finance-mcp --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=vamppog/india-finance-mcp", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "India Finance MCP", "description": "MCP server for Indian financial data. Get real-time mutual fund NAVs from AMFI (47,000+ schemes), validate GSTIN numbers with checksum verification, and more. Built for AI agents (Claude, ChatGPT, Cursor) via MCP protocol. REST API also available. Stock quotes coming in v1.1.", "version": "0.1", "x-build-id": "Icc2QufHrLQuXfLua" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/vamppog~india-finance-mcp/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-vamppog-india-finance-mcp", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/vamppog~india-finance-mcp/runs": { "post": { "operationId": "runs-sync-vamppog-india-finance-mcp", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/vamppog~india-finance-mcp/run-sync": { "post": { "operationId": "run-sync-vamppog-india-finance-mcp", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": {} }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```