Live-NSE-BSE-MCP by GirishKumarDV - MCP Server

Indian Stock Exchange MCP Server

This server provides access to live market data from Indian Stock Exchanges (BSE & NSE) through the Model Context Protocol (MCP), powered by IndianAPI.

🚀 Quick Start

Prerequisites

Python 3.8+
pip (Python package installer)
API Key from IndianAPI: Sign up at https://indianapi.in/ and obtain an API key for the Stock Market API

Installation

Note: This package is not yet published to PyPI. Please use source installation for now.

Option 1: Quick Install from Source (Recommended)

git clone https://github.com/GirishKumarDV/Live-NSE-BSE-MCP.git
cd Live-NSE-BSE-MCP
pip install -e .

Option 2: Development Installation

git clone https://github.com/GirishKumarDV/Live-NSE-BSE-MCP.git
cd Live-NSE-BSE-MCP
pip install -r requirements.txt
pip install -e .

Option 3: Manual Execution (No Installation)

If you prefer not to install the package:

git clone https://github.com/GirishKumarDV/Live-NSE-BSE-MCP.git
cd Live-NSE-BSE-MCP
pip install -r requirements.txt
# Run directly with: python -m ise_mcp.server

Important: Since the package isn't on PyPI yet, use module execution (python -m ise_mcp.server) or install from source for the console scripts to work.

Configuration

Get your API key:
- Visit https://indianapi.in/
- Sign up for a free account
- Navigate to the Stock Market API section
- Subscribe to get your API key

Configure environment variables:

# Copy the example environment file
cp env.example .env

# Edit .env and add your IndianAPI key
# ISE_API_KEY=your_indianapi_key_here

Usage

HTTP Server Mode (for web clients like Cursor, VSCode, Dify)

After installation, you can run the server in several ways:

Method 1: Module Execution (Recommended)

# From the project root directory
python -m ise_mcp.server

Method 2: Using Batch Script (Windows)

# Use the provided batch script (note the .\ prefix for PowerShell)
.\ise-mcp-server.bat

# Or with environment variables
$env:ISE_HTTP_PORT=9000; .\ise-mcp-server.bat

Method 3: Development Mode

# If not installed, run as module from parent directory
cd ..
python -m ise_mcp.server

Note: Console scripts from PyPI (ise-mcp-server) are not available yet. Use module execution or the batch script instead.

The server will start on http://localhost:8000 by default.

Stdio Mode (for direct MCP clients like Claude Desktop)

Method 1: Module Execution (Recommended)

# From the project root directory
python -m ise_mcp.stdio_server

Method 2: Using Batch Script (Windows)

# Use the existing batch script (note the .\ prefix for PowerShell)
.\ise-mcp-stdio.bat

Note: Console scripts from PyPI (ise-mcp-stdio) are not available yet. Use module execution or the batch script instead.

Important: Do NOT run the server files directly (e.g., python server.py) as this will cause import errors. Always use the console scripts or module execution.

🔧 Configuration

The server uses environment variables for configuration. Create a .env file in the project root with the following variables:

# Required: API Key from IndianAPI (https://indianapi.in/)
ISE_API_KEY=your_indianapi_key_here

# Optional: API Base URL (default: https://stock.indianapi.in/)
ISE_API_BASE_URL=https://stock.indianapi.in/

# Optional: Server configuration
ISE_HTTP_HOST=0.0.0.0
ISE_HTTP_PORT=8000
ISE_REQUEST_TIMEOUT=30
ISE_LOG_LEVEL=INFO

Important: The ISE_API_KEY is required and the server will not start without it. Make sure to add your .env file to .gitignore to prevent committing sensitive information.

🌐 Client Integrations

Claude Desktop Integration

Claude Desktop uses the stdio transport for direct MCP communication.

Step 1: Install the Server

Since the package isn't on PyPI yet, install from source:

git clone https://github.com/GirishKumarDV/Live-NSE-BSE-MCP.git
cd Live-NSE-BSE-MCP
pip install -e .

Step 2: Configure Claude Desktop

Windows: Edit %APPDATA%\Claude\claude_desktop_config.json macOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json

Choose one of the following configuration methods based on your setup:

Option 1: Using Virtual Environment Python (Most Reliable)

If you have a virtual environment with dependencies installed:

{
  "mcpServers": {
    "ise-mcp": {
      "command": "C:\\path\\to\\your\\project\\venv\\Scripts\\python.exe",
      "args": ["-m", "ise_mcp.stdio_server"],
      "cwd": "C:\\path\\to\\your\\project",
      "env": {
        "ISE_API_KEY": "your_indianapi_key_here"
      }
    }
  }
}

Option 2: Using PYTHONPATH (Recommended Fallback)

{
  "mcpServers": {
    "ise-mcp": {
      "command": "python",
      "args": ["-m", "ise_mcp.stdio_server"],
      "cwd": "C:\\path\\to\\your\\project",
      "env": {
        "ISE_API_KEY": "your_indianapi_key_here",
        "PYTHONPATH": "C:\\path\\to\\your\\project"
      }
    }
  }
}

Option 3: Using Batch Script (Windows)

{
  "mcpServers": {
    "ise-mcp": {
      "command": "C:\\path\\to\\your\\project\\ise-mcp-stdio.bat",
      "cwd": "C:\\path\\to\\your\\project",
      "env": {
        "ISE_API_KEY": "your_indianapi_key_here"
      }
    }
  }
}

Option 4: Direct File Execution

{
  "mcpServers": {
    "ise-mcp": {
      "command": "python",
      "args": ["ise_mcp/stdio_server.py"],
      "cwd": "C:\\path\\to\\your\\project",
      "env": {
        "ISE_API_KEY": "your_indianapi_key_here",
        "PYTHONPATH": "C:\\path\\to\\your\\project"
      }
    }
  }
}

Option 5: Using PowerShell (if execution policies allow)

{
  "mcpServers": {
    "ise-mcp": {
      "command": "powershell",
      "args": ["-Command", "cd 'C:\\path\\to\\your\\project'; python -m ise_mcp.stdio_server"],
      "env": {
        "ISE_API_KEY": "your_indianapi_key_here"
      }
    }
  }
}

Option 6: After Global Installation

If you've installed the package globally with pip install -e .:

{
  "mcpServers": {
    "ise-mcp": {
      "command": "python",
      "args": ["-m", "ise_mcp.stdio_server"],
      "env": {
        "ISE_API_KEY": "your_indianapi_key_here"
      }
    }
  }
}

macOS/Linux Equivalents:

For macOS/Linux, replace Windows paths with Unix-style paths:

C:\\path\\to\\your\\project becomes /path/to/your/project
venv\\Scripts\\python.exe becomes venv/bin/python
Use forward slashes / instead of backslashes \\

Notes:

Replace C:\\path\\to\\your\\project with your actual project path
Replace your_indianapi_key_here with your actual API key from IndianAPI
Try options in order - Option 1 (virtual environment) is most reliable
If one doesn't work, try the next option

Step 3: Restart Claude Desktop

After saving the configuration, restart Claude Desktop. You should see the ISE MCP tools available in your chat.

Testing Claude Integration

Once configured, you can ask Claude:

"Show me trending stocks in the Indian market"
"Get me data for Reliance Industries"
"What are the top gainers today?"

VSCode Integration

VSCode can use the HTTP transport to connect to the MCP server.

Step 1: Install MCP Extension

Install an MCP-compatible extension in VSCode or use the built-in MCP support if available.

Step 2: Start the HTTP Server

Clone and setup the server first:

# Clone the repository
git clone https://github.com/GirishKumarDV/Live-NSE-BSE-MCP.git
cd Live-NSE-BSE-MCP

# Install dependencies  
pip install -r requirements.txt

# Start the server
python -m ise_mcp.server

Step 3: Configure VSCode

Add to your VSCode settings.json:

{
  "mcp.servers": {
    "ise-mcp": {
      "url": "http://localhost:8000/jsonrpc",
      "type": "http"
    }
  }
}

Step 4: Set Environment Variables

Ensure your ISE_API_KEY is set:

# In your terminal before starting VSCode
export ISE_API_KEY=your_indianapi_key_here
code .

Cursor Integration

Cursor supports MCP through HTTP transport.

Step 1: Start the HTTP Server

Clone and setup the server first:

# Clone the repository
git clone https://github.com/GirishKumarDV/Live-NSE-BSE-MCP.git
cd Live-NSE-BSE-MCP

# Install dependencies  
pip install -r requirements.txt

# Start the server
python -m ise_mcp.server

Step 2: Configure Cursor

In Cursor, go to Settings → Extensions → MCP and add:

Server URL: http://localhost:8000/jsonrpc
Server Type: HTTP JSON-RPC

Step 3: Environment Setup

Make sure your API key is configured in your .env file:

ISE_API_KEY=your_indianapi_key_here

Testing Cursor Integration

You can now ask Cursor's AI:

"Use the ISE MCP to get stock data for TCS"
"Show me the most active stocks on NSE"

Other MCP Clients

HTTP Transport (Web Clients)

For any HTTP-based MCP client:

URL: http://localhost:8000/jsonrpc
Type: HTTP JSON-RPC 2.0
Content-Type: application/json

Stdio Transport (Command Line)

For stdio-based MCP clients:

# Clone and setup first
git clone https://github.com/GirishKumarDV/Live-NSE-BSE-MCP.git
cd Live-NSE-BSE-MCP
pip install -r requirements.txt

# Direct stdio connection
python -m ise_mcp.stdio_server

# Or with environment variables
ISE_API_KEY=your_key python -m ise_mcp.stdio_server

Dify Integration

Dify can connect using HTTP transport:

URL: http://localhost:8000/jsonrpc
Type: MCP over HTTP
Headers: Content-Type: application/json

Available Tools

The server provides the following tools for accessing Indian stock market data:

Market Data Tools

get_stock_data - Get detailed financial data for a specific company
get_trending_stocks - Get trending stocks with top gainers and losers
get_52_week_high_low - Get stocks with highest and lowest prices in the last 52 weeks
get_nse_most_active - Get most active stocks on NSE by trading volume
get_bse_most_active - Get most active stocks on BSE by trading volume
get_price_shockers - Get stocks with significant price changes

Research Tools

search_industry - Search for companies within a specific industry
get_analyst_recommendations - Get analyst target prices and recommendations
get_stock_forecasts - Get detailed forecast information for a stock
get_historical_data - Get historical stock data with various filters
get_historical_stats - Get historical statistics for a stock

Investment Tools

search_mutual_funds - Search for mutual funds
get_mutual_funds - Get latest mutual fund data with NAV and returns
get_commodities - Get real-time commodity futures data

🔗 API Endpoints

Health Check

GET http://localhost:8000/health

Server Information

GET http://localhost:8000/info

MCP JSON-RPC

POST http://localhost:8000/jsonrpc

📝 Example Usage

Get Stock Data

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_stock_data",
    "arguments": {
      "name": "Reliance"
    }
  },
  "id": 1
}

Get Trending Stocks

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_trending_stocks",
    "arguments": {}
  },
  "id": 2
}

🛠️ Development & Testing

Running Tests

The project includes several test files for different aspects of functionality:

1. Tool Testing

# Test individual MCP tools functionality
python tests/test_tools.py

2. Connection Testing

# Test basic HTTP connections and API responses
python tests/test_connection.py

3. Clean Tools Testing

# Test tool validation and clean responses
python tests/test_clean_tools.py

4. VSCode Integration Testing

# Test VSCode MCP integration
python tests/test_vscode_connection.py

5. Run All Tests

# If you have pytest installed (recommended)
pytest tests/

# Or run all test files manually
python tests/test_tools.py && python tests/test_connection.py && python tests/test_clean_tools.py && python tests/test_vscode_connection.py

Testing with Different Clients

Testing with curl

# Start the HTTP server
python -m ise_mcp.server

# Test health endpoint
curl http://localhost:8000/health

# Test server info
curl http://localhost:8000/info

# Test MCP tool call
curl -X POST http://localhost:8000/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_trending_stocks",
      "arguments": {}
    },
    "id": 1
  }'

Testing with Python Client

# Use the included Python client
cd client
python simple_mcp_client.py

# Or run the basic usage example
cd examples
python basic_usage.py

Debug Mode

Set the log level to DEBUG in your .env file:

ISE_LOG_LEVEL=DEBUG

Development Workflow

Setup Development Environment:

git clone https://github.com/GirishKumarDV/Live-NSE-BSE-MCP.git
cd Live-NSE-BSE-MCP
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -e .

Create Configuration:

cp env.example .env
# Edit .env and add your API key

Run Tests:
```
python tests/test_tools.py
```
Start Development Server:
```
python -m ise_mcp.server
```

🔒 Security

Environment Variables: All sensitive configuration is stored in environment variables
API Key Protection: The API key is never logged or exposed in responses
CORS: Proper CORS headers are set for cross-origin requests
Input Validation: All tool inputs are validated against JSON schemas

📦 Publishing to PyPI

Current Status: This package is not yet published to PyPI. Users must install from source.

Users should install from source using the methods described in the Installation section.

Development Installation

# Clone and install in development mode
git clone https://github.com/GirishKumarDV/Live-NSE-BSE-MCP.git
cd Live-NSE-BSE-MCP
pip install -e ".[dev]"

# Run tests
pytest tests/

# Format code
black .

# Type check
mypy ise_mcp/

🐛 Troubleshooting

Common Issues

Relative Import Error (attempted relative import with no known parent package):
- Problem: Running python server.py or python stdio_server.py directly
- Solution: Use module execution (python -m ise_mcp.server, python -m ise_mcp.stdio_server) or install from source with pip install -e .
Server won't start:
- Check that your ISE_API_KEY from IndianAPI is set in the .env file
- Verify the API key is valid and not expired
API errors:
- Verify your IndianAPI key is valid and has sufficient quota
- Check if you've subscribed to the Stock Market API on IndianAPI
Connection issues:
- Ensure the server is running on the correct host/port
- Check if port 8000 is available
- Verify firewall settings
CORS errors:
- The server includes CORS headers, but check your client configuration
- Ensure you're making requests to the correct endpoint
Module not found:
- Ensure you've installed the package with pip install -e . from the project directory
- Check if virtual environment is activated
- Note: PyPI installation (pip install ise-mcp-server) is not available yet
Import errors:
- Check Python version compatibility (requires Python 3.8+)
- Ensure all dependencies are installed: pip install -r requirements.txt

Installation Issues

Error: `No module named 'ise_mcp'`

# Solution 1: Install the package
pip install -e .

# Solution 2: Run from correct directory
cd /path/to/Live-NSE-BSE-MCP
python -m ise_mcp.server

Error: `ModuleNotFoundError: No module named 'mcp'`

# Install MCP dependency
pip install mcp>=1.0.0

# Or install all requirements
pip install -r requirements.txt

Client Integration Issues

Claude Desktop Not Detecting Server

Check configuration file location:
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Verify JSON syntax is valid
Restart Claude Desktop completely
Check console logs for error messages

VSCode/Cursor Connection Issues

Ensure HTTP server is running: python -m ise_mcp.server
Test server health: curl http://localhost:8000/health
Check if MCP extension is properly installed
Verify environment variables are set

Error Handling

The server provides detailed error messages in JSON-RPC format:

-32600: Invalid Request
-32601: Method not found
-32602: Invalid params
-32603: Internal error

Transport-Specific Issues

HTTP Transport

Check if port 8000 is available: netstat -an | grep 8000
Verify firewall settings
Test with curl http://localhost:8000/health
Check server logs for error messages

Stdio Transport

Ensure no other output to stdout
Check that environment variables are set
Verify MCP client configuration
Test stdio connection: echo '{"jsonrpc":"2.0","method":"ping","id":1}' | python -m ise_mcp.stdio_server

Development Issues

Tests Failing

# Check if server is running
curl http://localhost:8000/health

# Verify API key is set
echo $ISE_API_KEY

# Run individual tests
python tests/test_connection.py
python tests/test_tools.py

Debugging Server Issues

Enable debug logging in .env:
```
ISE_LOG_LEVEL=DEBUG
```
Check server logs for detailed error information
Test API endpoints manually with curl
Verify IndianAPI service status

📚 Related Projects

MCP Client: - Python client for testing
Examples: - Usage examples

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

IndianAPI Marketplace: https://indianapi.in/
Indian Stock API: https://stock.indianapi.in/
Model Context Protocol: https://modelcontextprotocol.io/
MCP Specification: https://spec.modelcontextprotocol.io/