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).

📑 Table of Contents

• What is MCP?
• Features
• Quick Start
• Installation
• API Tools
• Configuration
• Usage Examples
• Directory Structure
• Contributing
• 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

✨ 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

1. Clone & Install

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:

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

Get your free API key from: https://indianapi.in/

3. Build

npm run build

4. Run Server

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

🔧 Installation

Option 1: Direct Clone

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)

npm install indian-stock-exchange-mcp

Option 3: Via npx

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

⚙️ 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:

# .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

💡 Usage Examples

Example 1: Get Stock Details

# 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

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

Example 3: Historical Analysis

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

See 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

npm install
npm run build
node build/index.js

See docs/ARCHITECTURE.md for code structure.

📝 Contributing

Contributions are welcome! See 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 for detailed troubleshooting.

📞 Support

• GitHub Issues: Report bugs or request features
• Documentation: Check docs/ folder
• API Provider: Indian Stock Market API

📄 License

This project is licensed under the ISC License.

🙏 Acknowledgments

• Built with Model Context Protocol SDK
• Data provided by Indian Stock Market API
• Powered by TypeScript and Node.js

Made with ❤️ for the Indian Stock Market community