# InvestSights — Indian Stock Research MCP Server

**The Model Context Protocol server for deep Indian stock research — fundamentals, forensic accounting scores, DCF valuation, screening, prices, technicals and news for 6,000+ NSE & BSE stocks, from Claude, ChatGPT, Perplexity, Cursor & any AI assistant.**

[![npm version](https://img.shields.io/npm/v/investsights-mcp)](https://www.npmjs.com/package/investsights-mcp)
[![npm downloads](https://img.shields.io/npm/dm/investsights-mcp)](https://www.npmjs.com/package/investsights-mcp)
[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![MCP compatible](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io/)

[Documentation](https://investsights.in/mcp) •
[Quick Start](#quick-start) •
[Tools](#tools) •
[Example Prompts](#example-prompts) •
[npm](https://www.npmjs.com/package/investsights-mcp)

---

## What is this?

InvestSights MCP is a [Model Context Protocol](https://modelcontextprotocol.io/) server that connects AI assistants to **research-grade Indian stock market data** — the same engine that powers [investsights.in](https://investsights.in).

Where most market servers stop at quotes and screens, InvestSights adds a research layer: **forensic accounting scores** (Piotroski F, Beneish M, Altman Z — with bank-aware CAMELS handling), **multi-stage DCF + relative valuation**, **analyst consensus**, shareholding patterns and curated news — for 6,000+ NSE/BSE companies.

**Compatible with:** Claude.ai, Claude Desktop, Claude Code, ChatGPT, Perplexity, Cursor, Windsurf, VS Code (Copilot), Kiro, Zed, Codex, Gemini, Grok, OpenCode, and any MCP-compatible client.

## Quick Start

### Option 1: Remote MCP with OAuth (claude.ai, ChatGPT, Perplexity, Grok)

Add this URL as a custom connector in your AI chat app:

```
https://investsights.in/api/v2/mcp-public/mcp
```

First use opens a browser — sign in with your InvestSights account (Google login) and approve access on the consent screen. No token needed.

### Option 2: Remote MCP with Token (Claude Code, VS Code, Kiro, Zed)

For code editors that support URL-based MCP servers with custom headers:

1. Get a free key at [investsights.in/account/connected-apps](https://investsights.in/account/connected-apps)
2. Add to your MCP config:

```json
{
  "mcpServers": {
    "investsights": {
      "type": "url",
      "url": "https://investsights.in/api/v2/mcp-public/mcp",
      "headers": {
        "Authorization": "Bearer usk_YOUR_KEY_HERE"
      }
    }
  }
}
```

> URL-only client (no header support)? Use the key-in-URL form:
> `https://investsights.in/api/v2/mcp-public/usk_YOUR_KEY_HERE/mcp`

### Option 3: Local MCP via npm (Cursor, Windsurf, Claude Desktop, Codex, Gemini CLI)

For stdio-based MCP clients. No cloning or building — runs via `npx`:

1. Get a free key at [investsights.in/account/connected-apps](https://investsights.in/account/connected-apps)
2. Add to your MCP config:

```json
{
  "mcpServers": {
    "investsights": {
      "command": "npx",
      "args": ["-y", "investsights-mcp"],
      "env": {
        "INVESTSIGHTS_TOKEN": "usk_YOUR_KEY_HERE"
      }
    }
  }
}
```

> **Node.js 18+** required for the local option. Run `node --version` to check.

## How It Works

```
┌─────────────────┐   stdio (JSON-RPC)   ┌───────────────────┐     HTTPS     ┌─────────────────────┐
│  AI Assistant   │ ◄──────────────────► │  investsights-mcp │ ◄───────────► │   investsights.in   │
│  (Claude, etc.) │                      │   (npm package)   │               │  (research backend) │
└─────────────────┘                      └───────────────────┘               └─────────────────────┘
```

The npm package is a lightweight stdio bridge (~250 lines, **zero runtime dependencies**). It:

- Reads JSON-RPC from stdin, forwards to the remote InvestSights MCP server, writes responses to stdout
- Auto-detects framing: `Content-Length` (VS Code, Claude Desktop) or newline-delimited JSON (Claude Code, Kiro)
- Authenticates every request with your personal key as a Bearer token
- Handles SSE responses from the remote server

**All tools and their logic run on the remote server — the npm package is just the transport layer.**

## Authentication

| Method | How it works | Best for |
| --- | --- | --- |
| **OAuth (Google sign-in)** | Browser sign-in + consent screen, revocable anytime | AI chat apps (claude.ai, ChatGPT, Perplexity, Grok) |
| **Personal key (remote)** | `Authorization: Bearer usk_...` header, or key-in-URL | Code editors with URL-based MCP (VS Code, Kiro, Zed) |
| **Personal key (local)** | `INVESTSIGHTS_TOKEN` env var via npx | stdio MCP clients (Cursor, Windsurf, Claude Desktop) |

Create and revoke keys anytime at [investsights.in/account/connected-apps](https://investsights.in/account/connected-apps). Same free limits across every method.

## Tools

A curated pack of fast, read-only research tools — your AI picks the right one automatically.

### 🏢 Company Research

| Tool | Description |
| --- | --- |
| `get_stock_financials` | Fundamentals and key ratios — P/E, P/B, ROE, ROCE, D/E, margins, growth. |
| `get_shareholding` | Promoter, FII, DII and public shareholding patterns over time. |
| `get_stock_comparison` | Side-by-side comparison of fundamentals, valuations and technicals. |

### 🔬 Quality & Valuation

| Tool | Description |
| --- | --- |
| `get_forensic_score` | Forensic accounting checks — Piotroski F-Score, Beneish M-Score, Altman Z-Score. Bank-aware: financials are assessed on CAMELS instead of manufacturing models. |
| `get_valuation` | Multi-stage DCF with bull/base/bear scenarios and sensitivity, plus peer-relative valuation — computed server-side, never hallucinated. |
| `get_analyst_consensus` | Analyst estimates, grades and consensus. |

### 📊 Screening

| Tool | Description |
| --- | --- |
| `screen_stocks` | Multi-factor stock screener across fundamentals, quality and momentum. |

### 📈 Prices & Technicals

| Tool | Description |
| --- | --- |
| `get_price_history` | Daily OHLCV history with technical context. |
| `get_technical_indicators` | RSI, moving averages (5/20/50/200) and more. |

### 📰 Market & News

| Tool | Description |
| --- | --- |
| `get_market_overview` | Indices, breadth and sector snapshot for the Indian market. |
| `get_stock_news` | Curated, AI-summarised stock news. |
| `get_earnings_calendar` | Results dates and economic events. |

> **Enterprise:** the full 40+ tool catalog — GraphRAG document intelligence, earnings-call analysis, corporate-governance graphs, superstar-investor tracking, portfolio analytics — is available with dedicated keys and custom limits. Contact **connect@investsights.in**.

## Example Prompts

### Stock Research

```
"Compare HDFC Bank vs ICICI Bank — profit growth, ROE, valuation and
 shareholding trends right now"

"Pull TCS fundamentals and shareholding — is FII holding rising or falling?"
```

### Forensic Quality

```
"Run a forensic accounting check on Suzlon — Piotroski, Beneish, Altman.
 Any red flags?"

"Which looks financially healthier on forensic scores: Zomato or Swiggy?"
```

### Valuation

```
"What does a DCF say about TCS at today's price? Show bull, base and bear
 scenarios with the key assumptions"
```

### Screening + Technicals

```
"Find stocks with ROE > 18%, low debt, and RSI under 40 — oversold quality
 names"

"Screen mid-caps with improving margins and P/E below 20 — top 15"
```

### Market Briefing

```
"Today's Indian market overview — index moves, strongest sector, and this
 week's earnings calendar"
```

## Data Coverage

| Category | What's included |
| --- | --- |
| **Stocks** | 6,000+ NSE & BSE listed companies |
| **Fundamentals** | Key ratios, growth metrics, quarterly + annual context |
| **Forensic** | Piotroski F, Beneish M, Altman Z — bank-aware (CAMELS) |
| **Valuation** | Multi-stage FCFF DCF (scenarios + sensitivity), peer-relative valuation |
| **Screener** | 163 fundamental + quality + momentum filters |
| **Prices & technicals** | EOD OHLCV, RSI, MA-5/20/50/200 |
| **Ownership** | Promoter / FII / DII / public shareholding over time |
| **News & events** | AI-summarised stock news, earnings calendar, economic events |

## Environment Variables

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `INVESTSIGHTS_TOKEN` | Yes (local) | — | Personal key from [investsights.in/account/connected-apps](https://investsights.in/account/connected-apps) |
| `INVESTSIGHTS_MCP_URL` | No | `https://investsights.in/api/v2/mcp-public/mcp` | Override remote server URL |
| `INVESTSIGHTS_DEBUG` | No | `0` | Set to `1` for debug logging to stderr |

## Rate Limits

| Plan | Per minute | Per day |
| --- | --- | --- |
| Free (every registered account) | 10 requests | 100 requests |
| Pro | 30 requests | 1,000 requests |

Higher limits and the full tool catalog are available for teams and platforms — **connect@investsights.in**.

## Troubleshooting

| Problem | Solution |
| --- | --- |
| `INVESTSIGHTS_TOKEN environment variable is required` | Add your key to the `env` section of your MCP config |
| `Authentication failed (401)` | Key revoked or mistyped — create a new one at [investsights.in/account/connected-apps](https://investsights.in/account/connected-apps) |
| `Rate limit exceeded` | Wait for the window to reset, or upgrade for higher limits |
| Server not responding | Ensure Node.js 18+ is installed (`node --version`) |
| Network errors | The bridge needs to reach `investsights.in` |

Set `INVESTSIGHTS_DEBUG=1` for detailed logging to stderr.

## Links

- **[investsights.in](https://investsights.in)** — Web platform
- **[investsights.in/mcp](https://investsights.in/mcp)** — MCP documentation & setup guide
- **[investsights.in/docs](https://investsights.in/docs)** — Full developer & tool reference
- **[npm: investsights-mcp](https://www.npmjs.com/package/investsights-mcp)** — npm package

## Compliance

InvestSights is an analytics platform and is **not SEBI-registered** as a Research Analyst or Investment Adviser. Every tool is **read-only** and returns data, ratios and scores — never buy/sell recommendations, target prices or personalised advice. All output is educational; consult a SEBI-registered adviser before investing. Investments in securities markets are subject to market risks.

## Contributing

Issues and pull requests are welcome for the bridge itself. For bugs, include the error message and your MCP client name/version.

## License

[MIT](LICENSE) — the bridge is free to use, modify and distribute. The InvestSights platform and its data services are proprietary.

---

Built by [InvestSights](https://investsights.in) — a product of **SocialCoffee DigiTech Pvt Ltd**