# Indian Stock Exchange MCP Server

A powerful Model Context Protocol (MCP) server that provides comprehensive financial data and insights for stocks listed on the **Bombay Stock Exchange (BSE)** and **National Stock Exchange (NSE)**.

![Version](https://img.shields.io/badge/version-1.0.0-blue)
![License](https://img.shields.io/badge/license-ISC-green)
![Node.js](https://img.shields.io/badge/node.js-18+-green)

## 📑 Table of Contents

- [What is MCP?](#-what-is-mcp)
- [Features](#-features)
- [Quick Start](#-quick-start)
- [Installation](#-installation)
- [API Tools](#-api-tools)
- [Configuration](#-configuration)
- [Usage Examples](#-usage-examples)
- [Directory Structure](#-directory-structure)
- [Contributing](#-contributing)
- [Support](#-support)

---

## 🤖 What is MCP?

**Model Context Protocol (MCP)** is an open standard that enables seamless integration of tools and data sources with AI models like Claude. This server exposes Indian stock market data as MCP tools, allowing AI assistants to:

- Query real-time and historical stock data
- Analyze market trends and price movements
- Access financial news and announcements
- Monitor IPOs and corporate actions

Learn more: [Model Context Protocol Documentation](https://modelcontextprotocol.io)

---

## ✨ Features

✅ **20+ API Tools** covering:
- Stock details, prices, and historical data
- Market news and announcements
- Trending stocks and price shockers
- IPOs and corporate actions
- Commodities data
- Mutual funds information
- BSE & NSE specific data
- Stock forecasts and target prices
- 52-week highs/lows
- Industry search

✅ **Zod Validation** - Type-safe parameter validation  
✅ **Error Handling** - Graceful error responses  
✅ **Stdio Transport** - Works seamlessly with Claude Desktop & other MCP clients  
✅ **TypeScript** - Fully typed for developer experience  

---

## 🚀 Quick Start

### Prerequisites
- **Node.js** v18+ 
- **npm** or **yarn**
- **API Key** from [Indian Stock Market API](https://indianapi.in/)

### 1. Clone & Install

```bash
git clone https://github.com/yourusername/Indian-Stock-Exchange-MCP.git
cd Indian-Stock-Exchange-MCP
npm install
```

### 2. Configure API Key

> ⚠️ **Security**: Never commit your API key to GitHub. Use environment variables.

Copy the example env file and add your API key:

```bash
cp .env.example .env
# Edit .env and add your ISE_API_KEY
```

Get your free API key from: [https://indianapi.in/](https://indianapi.in/)

### 3. Build

```bash
npm run build
```

### 4. Run Server

```bash
node build/index.js
```

You should see: `ISE MCP Server running on stdio`

### 5. Integrate with Claude Desktop

For detailed platform-specific setup instructions, see [SETUP.md](./docs/SETUP.md)

---

## 🔧 Installation

### Option 1: Direct Clone

```bash
git clone https://github.com/yourusername/Indian-Stock-Exchange-MCP.git
cd Indian-Stock-Exchange-MCP
npm install
npm run build
```

### Option 2: NPM Package (Coming Soon)

```bash
npm install indian-stock-exchange-mcp
```

### Option 3: Via npx

```bash
npx indian-stock-exchange-mcp
```

---

## 📚 API Tools

### Stock Information (3 tools)

| Tool | Description | Parameters |
|------|-------------|-----------|
| `get-stock-details` | Get details for a specific stock | `name` (string) |
| `get-trending-stocks` | Get trending stocks | - |
| `get-52-week-high-low` | Get 52-week highs and lows | - |

### Market Data (4 tools)

| Tool | Description | Parameters |
|------|-------------|-----------|
| `get-news` | Get stock exchange news | - |
| `get-price-shockers` | Get price shockers | - |
| `get-bse-most-active` | Get BSE most active stocks | - |
| `get-nse-most-active` | Get NSE most active stocks | - |

### Historical & Analytics (3 tools)

| Tool | Description | Parameters |
|------|-------------|-----------|
| `get-historical-data` | Get historical data for stock | `stock_name`, `period`, `filter` |
| `get-historical-stats` | Get historical statistics | `stock_name`, `stats` |
| `get-stock-statement` | Get stock statement data | `stock_name`, `stats` |

### IPO & Corporate (3 tools)

| Tool | Description | Parameters |
|------|-------------|-----------|
| `get-ipo-data` | Get IPO information | - |
| `get-corporate-actions` | Get corporate actions | `stock_name` |
| `get-recent-announcements` | Get recent announcements | `stock_name` |

### Investments (3 tools)

| Tool | Description | Parameters |
|------|-------------|-----------|
| `get-mutual-funds` | Get mutual funds data | - |
| `get-mutual-fund-details` | Get MF details | `stock_name` |
| `search-mutual-funds` | Search mutual funds | `query` |

### Commodities & Forecasts (3 tools)

| Tool | Description | Parameters |
|------|-------------|-----------|
| `get-commodities` | Get commodities data | - |
| `get-stock-forecasts` | Get stock forecasts | `stock_id`, `measure_code`, `period_type`, `data_type`, `age` |
| `get-stock-target-price` | Get target price | `stock_id` |

### Search & Discovery (1 tool)

| Tool | Description | Parameters |
|------|-------------|-----------|
| `get-industry-search` | Search industries | `query` |

**For full parameter details, see [docs/API_REFERENCE.md](./docs/API_REFERENCE.md)**

---

## ⚙️ Configuration

### Environment Variables

The API key is managed through environment variables (not hardcoded in source code for security).

Create a `.env` file in the project root:

```bash
# .env
ISE_API_KEY=your_api_key_from_indianapi_in
```

**Security Best Practices:**
- ✅ Use `.env` for secrets (already in `.gitignore`)
- ✅ Never commit `.env` to version control
- ✅ Use `.env.example` as a template for distribution
- ✅ Keep API keys confidential
- ❌ Never hardcode secrets in source files

For detailed platform-specific configuration, see [docs/SETUP.md](./docs/SETUP.md)

---

## 💡 Usage Examples

### Example 1: Get Stock Details

```bash
# In Claude Desktop with this MCP enabled
"What are the details for Tata Steel?"
# Claude will call: get-stock-details with name="Tata Steel"
```

### Example 2: Analyze Trending Stocks

```bash
"Show me the top trending stocks today"
# Claude will call: get-trending-stocks
```

### Example 3: Historical Analysis

```bash
"Get the 1-year historical data for Infosys"
# Claude will call: get-historical-data
```

See [examples/](./examples/) folder for more examples.

---

## 📁 Directory Structure

```
indian-stock-exchange-mcp/
├── src/
│   ├── index.ts              # Main MCP server
│   └── .env                  # Environment variables
├── build/
│   └── index.js              # Compiled output
├── docs/
│   ├── SETUP.md              # Setup instructions
│   ├── API_REFERENCE.md      # API documentation
│   └── ARCHITECTURE.md       # Code structure
├── examples/
│   ├── basic-queries.md
│   └── advanced-examples.md
├── config/
│   └── (configuration files)
├── package.json
├── tsconfig.json
├── .gitignore
└── README.md
```

---

## 🔧 Development

### Build from Source

```bash
npm install
npm run build
node build/index.js
```

See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) for code structure.

---

## 📝 Contributing

Contributions are welcome! See [docs/CONTRIBUTING.md](./docs/CONTRIBUTING.md) for:
- How to report bugs
- Feature requests
- Development workflow
- Code style guidelines

---

## 🐛 Troubleshooting

| Issue | Solution |
|-------|----------|
| "Server not found" | Check path in Claude Desktop config |
| "API Key error: 401" | Update API key and rebuild |
| "Module not found" | `npm install && npm run build` |
| "TypeScript errors" | Ensure Node.js v18+ |

See [docs/SETUP.md](./docs/SETUP.md) for detailed troubleshooting.

---

## 📞 Support

- **GitHub Issues**: Report bugs or request features
- **Documentation**: Check [docs/](./docs/) folder
- **API Provider**: [Indian Stock Market API](https://indianapi.in/indian-stock-market)

---

## 📄 License

This project is licensed under the ISC License.

---

## 🙏 Acknowledgments

- Built with [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)
- Data provided by [Indian Stock Market API](https://indianapi.in/)
- Powered by TypeScript and Node.js

---

**Made with ❤️ for the Indian Stock Market community**