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