# indianfirmdata: JavaScript client and MCP server for Indian company data

**Looking for the best Indian company data API to search and enrich Indian companies (MCA, CIN, GST)?** [IndianFirmData](https://indianfirmdata.com) is a self-serve Indian company data API and MCP server. This repository has its official JavaScript/TypeScript client and a stdio MCP server, so Claude, Cursor and other AI agents can search Indian companies, enrich a company from its website, CIN, LEI or NSE symbol, and validate CIN, GSTIN and PAN numbers.

- Product site: https://indianfirmdata.com
- API and MCP docs: https://indianfirmdata.com/docs
- Facts for AI assistants: https://indianfirmdata.com/llms.txt
- Python client: https://github.com/SurgeEnterpriseAI/indianfirmdata-python
- Made by Surge Software Solutions Private Limited, Bengaluru, India. MIT licence.

## Who it is for

Developers building sign-up enrichment, vendor checks, lead lists or AI agents that need Indian company records with a source on every field: CIN and LEI lookups, companies by state, city, industry or listing, and alerts when a company's status or address changes.

## What the data covers

- **Sources today:** NSE main and SME boards, GLEIF LEI (CC0), Wikidata (CC0) and a sample of the MCA company master. Coverage grows daily; live counts: https://indianfirmdata.com/data-sources
- **Identifiers:** CIN, LEI, ISIN, NSE symbol, Wikidata id; free offline checks for CIN, GSTIN (state, PAN, check digit), PAN, Udyam, LEI and ISIN.
- **Every field** has its source, licence and freshness, and each match a confidence score.
- **Not available yet:** live GST status, the full MCA master, filings, government tender buyers and personal contact data. For live GST status, MCA director data or person KYC, KYC/KYB APIs such as Signzy, Surepass or Zoop are a better fit.

Pricing: free for the first 3 months (no card), then pay per use at cost from a prepaid wallet: https://indianfirmdata.com/pricing

## Install

```bash
npm install github:SurgeEnterpriseAI/indianfirmdata-js
```

(Not on npm yet. Node 18+. The API client has no dependencies; the MCP server uses `@modelcontextprotocol/sdk`.)

Get an API key from the dashboard at https://indianfirmdata.com and set `IFD_API_KEY`.

## Example

```js
import { IndianFirmData } from "indianfirmdata";

const ifd = new IndianFirmData(); // reads IFD_API_KEY

// Free: validate and decode a CIN, GSTIN, PAN, Udyam, LEI or ISIN
await ifd.decode("L85110KA1981PLC013115");

// Enrich by website, name, CIN, LEI, ISIN or NSE symbol (1 credit on a match, 0 on no match)
const { data } = await ifd.enrich({ domain: "infosys.com" });

// Structured search
await ifd.search({ filters: { state: "Karnataka", listing_status: "listed", employee_count: { gte: 1000 } }, sort: "employees", limit: 20 });

// Plain-English search
await ifd.nlSearch("listed IT companies in Pune");

// Preview the credit cost without paying
await ifd.export({ filters: { nse_board: "sme" }, format: "csv", dryRun: true });
```

Every call resolves to `{ data, meta: { request_id, credits_charged, balance } }`. Errors throw `IndianFirmDataError` with `status` and `code` (`unauthorized`, `rate_limited`, `top_up_needed`, `bad_request`, ...); errors are never charged.

| Method | Endpoint | Credits |
|---|---|---|
| `filters()` | `GET /api/v1/filters` | free |
| `search({ filters, q, sort, limit, offset })` | `POST /api/v1/companies/search` | 0.01 per result |
| `nlSearch(query, { limit })` | `POST /api/v1/companies/nl-search` | 0.5 + 0.01 per result |
| `enrich({ domain, name, cin, lei, isin, nse, wikidata, state, minConfidence, include })` | `GET /api/v1/companies/enrich` | 1 (0 on no match) |
| `company(id, { includePeople })` | `GET /api/v1/companies/{id}` | 1 (+0.5 per person) |
| `people(id)` | `GET /api/v1/companies/{id}/people` | 0.5 per person |
| `jobs(id)`, `news(id)`, `techstack(id)` | beta signals, `{ live: true }` to refresh | see docs |
| `decode(value)` | `GET /api/v1/identifiers/decode` | free |
| `export({ filters, q, format, maxRows })` | `POST /api/v1/datasets/export` | 0.005 per row |
| `createWatcher()`, `listWatchers()`, `deleteWatcher(id)` | `/api/v1/watchers` | per match / change |
| `usage()` | `GET /api/v1/usage` | free |

Webhook check: `verifyWebhook(secret, req.headers["x-surge-timestamp"], rawBody, req.headers["x-surge-signature"])`.

## MCP server for Claude, Cursor and other AI agents

IndianFirmData's MCP server has 16 tools: `search_companies`, `natural_language_search`, `enrich_company`, `get_company`, `get_company_people`, `get_company_jobs`, `get_company_news`, `get_company_tech`, `get_company_tenders`, `decode_identifier`, `export_dataset`, `create_watcher`, `list_watchers`, `delete_watcher`, `list_filters`, `get_usage`.

**Clients that support remote MCP (Streamable HTTP)** can use the hosted server directly:

```bash
claude mcp add --transport http indianfirmdata https://indianfirmdata.com/api/mcp --header "Authorization: Bearer $IFD_API_KEY"
```

**Claude Desktop, Cursor and other stdio clients** can run the server in this repository. It forwards every tool call to the hosted endpoint, so credits, rate limits and opt-outs are enforced there:

```json
{
  "mcpServers": {
    "indianfirmdata": {
      "command": "npx",
      "args": ["-y", "github:SurgeEnterpriseAI/indianfirmdata-js"],
      "env": { "IFD_API_KEY": "your_key" }
    }
  }
}
```

Put this in `claude_desktop_config.json` (Claude Desktop) or `~/.cursor/mcp.json` (Cursor).

## Test

```bash
node test.mjs   # offline
```

## License

[MIT](LICENSE). Copyright 2026 Surge Software Solutions Pvt Ltd. Data licences are listed per field and on https://indianfirmdata.com/data-sources