Indian Stock Analysis MCP Server

A Model Context Protocol (MCP) server for interacting with MongoDB stock data to provide portfolio recommendations and market insights, exclusively for the Indian stock market (NSE/BSE).

Overview

This MCP server integrates with:

MongoDB database (stock_data) for direct stock data access
Alpha Vantage API for Indian market data (NSE/BSE only) with free tier limitations
Knowledge Graph for persistent Indian stock analysis

It enables Claude to access your Indian stock portfolio holdings, analyze stock performance, and provide personalized recommendations directly through the Claude desktop app, while building a persistent knowledge graph for improved context awareness.

Features

Exclusive Indian Market Focus: Designed specifically for NSE and BSE listed stocks
Direct MongoDB Access: Queries MongoDB directly without going through an API layer
Knowledge Graph Integration: Maintains persistent analysis data for Indian stocks
Alpha Vantage Rate Limiting: Handles free tier API limitations with automatic rate limiting
Modular Architecture: Clean, maintainable code structure with separation of concerns
Environment Configuration: Uses .env for easy configuration
LLM-Optimized Data: Automatically limits and simplifies data responses to be easily processed by Claude
Segmented Portfolio Analysis: Processes large portfolios in smaller segments to prevent timeouts

Installation

Prerequisites

Python 3.9+
MongoDB running on localhost:27017 with database "stock_data"
Alpha Vantage API key (free tier supported, get one at https://www.alphavantage.co/support/#api-key)
Claude Desktop app (available at https://claude.ai/download)

Setup

Clone this repository:

git clone <repository-url>
cd stock-mcp-server

Install dependencies:
```
pip install -r requirements.txt
```
Create a .env file from the example:
```
cp .env.example .env
```

Edit the .env file to configure your settings:

# MongoDB Configuration
MONGODB_URI=mongodb://localhost:27017
MONGODB_DB_NAME=stock_data

# Alpha Vantage API
ALPHA_VANTAGE_API_KEY=your_api_key_here

# Indian Stock Market Settings
ALPHA_VANTAGE_DEFAULT_EXCHANGE=NSE  # NSE or BSE

Usage

Start the MCP Server

python server.py

Configure Claude Desktop App

Claude Desktop uses a configuration file to connect to MCP servers. You'll need to create or edit this file to include your stock analysis server.

Create or edit the configuration file at:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the stock analysis MCP server configuration:

{
  "mcpServers": {
    "stock-analysis-mcp": {
      "command": "/path/to/your/python",
      "args": [
        "/path/to/stock_mcp_server/server.py"
      ],
      "cwd": "/path/to/stock_mcp_server",
      "env": {
        "ALPHA_VANTAGE_API_KEY": "your_api_key_here",
        "MONGODB_URI": "mongodb://localhost:27017",
        "MONGODB_DB_NAME": "stock_data",
        "MONGODB_HOLDINGS_COLLECTION": "holdings",
        "MONGODB_FINANCIALS_COLLECTION": "detailed_financials",
        "MONGODB_KNOWLEDGE_GRAPH_COLLECTION": "stock_knowledge_graph",
        "ALPHA_VANTAGE_BASE_URL": "https://www.alphavantage.co/query",
        "ALPHA_VANTAGE_RATE_LIMIT_MINUTE": "5",
        "ALPHA_VANTAGE_RATE_LIMIT_DAY": "500",
        "ALPHA_VANTAGE_DEFAULT_EXCHANGE": "NSE",
        "MCP_SERVER_NAME": "stock-analysis-mcp",
        "MCP_SERVER_VERSION": "0.1.0",
        "LOG_LEVEL": "INFO",
        "CACHE_ENABLED": "True",
        "CACHE_TTL": "3600"
      }
    }
  }
}

Important Notes:

Use the full path to your Python executable (e.g., /usr/bin/python3 or C:\Python39\python.exe)
The server key stock-analysis-mcp must use hyphens, not underscores
The MCP_SERVER_NAME in env must match the server key
Make sure all paths are absolute paths

Start or restart Claude Desktop
Verify the server connection:
- Open Claude Desktop
- The tools icon (hammer) should appear in the interface
- Start a new conversation (important - new tools may not appear in existing conversations)
- Try asking about your stock portfolio

Example Prompts

Once configured, you can ask Claude:

"Can you provide a summary of my portfolio?"
"Analyze segment 1 of my portfolio"
"Analyze the next segment of my portfolio with segment_size=8"
"Analyze segment 3 of my portfolio with detailed metrics"
"What are the stocks in segment 2 of my portfolio?"
"Which sectors are most represented in my portfolio?"
"Can you provide recommendations on my Indian stock portfolio?"
"Analyze the banking stocks in my portfolio"
"What market trends should I be aware of in the Indian market this quarter?"
"Which stocks in my portfolio should I consider selling?"
"What new NSE stocks would complement my current portfolio?"
"Find me the best performing stocks on BSE this week"
"Can you find information about Reliance Industries stock?"
"What are the technical indicators for TCS stock?"
"Search for HDFC related stocks in the Indian market"

Troubleshooting

MCP Tools Not Appearing

If the tools aren't appearing in Claude despite successful server startup:

Check your logs:

tail -f ~/Library/Logs/Claude/mcp-server-stock-analysis-mcp.log

Verify server naming:
- Ensure the server key in claude_desktop_config.json uses hyphens (stock-analysis-mcp)
- Make sure the MCP_SERVER_NAME environment variable matches this name
Start a new conversation in Claude after making changes
Enable developer mode in Claude's settings
Check paths: Make sure all paths in the configuration are absolute and correct
Full Python path: Use the full path to your Python executable (e.g., run which python to find it)
Check Claude app log:
```
tail -f ~/Library/Logs/Claude/app.log
```

Common Issues

Python not found: Ensure the Python path in the configuration is correct
MongoDB connection issues: Check that MongoDB is running on the configured URI
Tool schema issues: Make sure all tools have proper schema definitions
Claude Desktop version: Keep Claude Desktop updated to the latest version
Server name mismatch: Server name in code must match configuration file
Large data responses: If Claude struggles processing large datasets, use segmented analysis:
- First get a portfolio summary with get_portfolio_summary
- Then analyze one segment at a time with portfolio_analysis using the segment parameter
- Use smaller segment sizes (3-5 stocks) for detailed analysis

Handling Large Portfolios

For large portfolios (20+ stocks), the server implements a segmented approach:

Get Portfolio Summary:
- Use get_portfolio_summary to see an overview of your portfolio
- This shows total stocks, sectors, and recommended segmentation
Analyze in Segments:
- Use portfolio_analysis with the segment parameter
- Start with segment 1, then progress through each segment
- Example: "Analyze segment 1 of my portfolio", then "Analyze segment 2..."
Control Segment Size:
- Default segment size is 5 stocks
- Use segment_size parameter to adjust (1-5 stocks per segment)
- Example: "Analyze segment 1 with segment_size=3 for detailed analysis"
Request Levels of Detail:
- Use include_details=false for quick overview (default)
- Use include_details=true for comprehensive metrics and insights
- When using detailed analysis, segment size is automatically reduced to prevent timeouts
Response Size Management:
- The server automatically monitors response size and simplifies data if needed
- Text fields are truncated to prevent overwhelming Claude
- Financial metrics are compressed to focus on essential information
- If a response would be too large, it's automatically simplified with a notification

Performance Optimizations

The server includes several optimizations to ensure Claude can process stock data efficiently:

Adaptive Response Sizing:
- Automatic monitoring of response size during processing
- Dynamic simplification when responses exceed size thresholds
- Truncation of text fields to 50-100 characters maximum
- Removal of non-essential data fields
Financial Data Compression:
- Automatic compression of financial data responses
- Limiting historical data to the 2 most recent periods
- Removal of metadata and internal fields
- Prioritization of essential metrics over comprehensive data
Parameter Limits:
- Portfolio analysis: Maximum 15 stocks, 5 per segment (3 for detailed analysis)
- Stock recommendations: Maximum 8 recommendations
- Removal analysis: Maximum 10 stocks analyzed for removal
- Market trends: Maximum 8 trending stocks
Intelligent Segmentation:
- Automatic adjustment of segment size based on analysis type
- Smaller segments for detailed analysis to prevent timeouts
- Progress tracking during analysis to identify bottlenecks
Response Size Management:
- Real-time monitoring of response size during processing
- Automatic simplification when responses exceed size thresholds
- Emergency fallback to minimal data when responses would be too large
- Detailed logging of response sizes for troubleshooting
Intelligent Internal Handling:
- Analysis functions use complete data internally while presenting simplified results
- Market trend recommendations filter out stocks already in portfolio
- Financial data compression preserves critical metrics while reducing size

These optimizations ensure Claude can process your stock data efficiently without being overwhelmed by excessive information or experiencing timeouts.

Testing

This repository includes a comprehensive test suite for validating the functionality of the MCP server.

Available Tests

test_mcp_server.py: A comprehensive test script that validates all endpoints and tools in the MCP server.
test_client.py: A simple client for testing MCP server endpoints.
test_server_startup.sh: Script to test the server startup process

Running the Tests

Quick Startup Test

To verify the server can start properly:

./test_server_startup.sh

Comprehensive Test Script

To run the comprehensive test script:

python test_mcp_server.py

This will test all aspects of the server, including:

MongoDB connection
Database operations (portfolio holdings, knowledge graph)
Indian stock symbol formatting
Alpha Vantage API integration
Trending stocks functionality
MCP tools handler

Skip Alpha Vantage API Tests

If you want to skip the tests that make actual API calls to Alpha Vantage (to avoid rate limits):

python test_mcp_server.py --skip-alpha-vantage

Test Results

The script will output detailed logs to both the console and a test_mcp_server.log file. At the end, you'll see a summary of test results:

=== Test Results Summary ===
database_connection: ✅ PASSED
portfolio_holdings: ✅ PASSED
knowledge_graph: ✅ PASSED
symbol_formatting: ✅ PASSED
alpha_vantage_api: ✅ PASSED
trending_stocks: ✅ PASSED
tools_handler: ✅ PASSED

Overall: 7/7 tests passed

Troubleshooting Tests

If tests fail, check the following:

Database Connection: Ensure MongoDB is running on the configured URI (default: mongodb://localhost:27017) and the stock_data database exists.
Alpha Vantage API: Check that your API key is set in the .env file and has not exceeded rate limits.
Data Availability: Some tests require existing data in the MongoDB collections (e.g., portfolio holdings). Ensure your database has the necessary data.
Network Issues: The Alpha Vantage tests require internet connectivity.

Exit Codes

0: All tests passed
1: One or more tests failed

This allows you to integrate the tests into continuous integration pipelines that check for non-zero exit codes.

Indian Stock Market Notes

When working with the Indian stock market, keep in mind:

NSE symbols are formatted as NSE:SYMBOL (e.g., NSE:RELIANCE)
BSE symbols are formatted as BSE:CODE (e.g., BSE:500325)
If no exchange is specified, the default is NSE
Alpha Vantage free tier is limited to 5 calls per minute, 500 calls per day
This server is exclusively designed for Indian stocks and will not process requests for other markets

Architecture

The project follows a modular architecture for better maintainability and separation of concerns:

├── server.py           # Main entry point
├── src/                # Source code
│   ├── __init__.py     # Package initialization
│   ├── config.py       # Configuration module
│   ├── handlers/       # MCP handler implementations
│   │   ├── __init__.py
│   │   ├── resources.py  # Resource handlers
│   │   ├── tools.py      # Tool handlers for Indian stock analysis
│   │   └── prompts.py    # Prompt handlers
│   └── utils/          # Utility modules
│       ├── __init__.py
│       ├── database.py   # MongoDB operations
│       └── alpha_vantage.py  # Alpha Vantage API operations for Indian market
├── test_mcp_server.py  # Comprehensive test script
├── test_client.py      # Simple test client
├── requirements.txt    # Dependencies
└── .env.example        # Example environment configuration

Tools

The server provides the following MCP tools, organized by category:

Portfolio Analysis

Get Portfolio Holdings: Retrieve current Indian stock portfolio with basic information
- Parameters:
  - limit: Maximum number of holdings to return (default: 10, max: 50)
  - summary: Return simplified stock data (default: true)
Get Portfolio Summary: Get a high-level overview of the portfolio
- Returns:
  - Total stocks count
  - Sector breakdown
  - Segmentation guide
  - Analysis recommendations
Analyze Portfolio: Analyze portfolio holdings with metrics and recommendations
- Parameters:
  - limit: Maximum stocks to analyze (default: 10, max: 15)
  - include_details: Include comprehensive metrics (default: false)
  - segment: Which segment of stocks to analyze (default: 1)
  - segment_size: Number of stocks per segment (default: 5, max: 5)
- Notes:
  - For detailed analysis, segment size is automatically reduced to 3
  - Response size is monitored and simplified if needed
  - Text fields are truncated to 50 characters maximum

Stock Recommendations

Get Stock Recommendations: Get recommendations for Indian stocks to add based on financial metrics
- Parameters:
  - criteria: Type of recommendations to get (e.g., "growth", "value", "dividend") (default: "growth")
  - limit: Maximum number of recommendations to return (default: 5, max: 8)
- Notes:
  - Responses are optimized for Claude with text field truncation
  - Recommendations are filtered to exclude stocks already in portfolio
  - Response size is monitored and simplified if needed
Get Removal Recommendations: Identify Indian stocks that should be removed from portfolio
- Parameters:
  - limit: Maximum number of stocks to analyze (default: 5, max: 10)
- Notes:
  - Automatically analyzes portfolio holdings for removal candidates
  - Identifies stocks with declining profits, bearish trends, or low fundamental scores
  - Response size is monitored and simplified if needed

Market Trends

Get Market Trend Recommendations: Find must-buy Indian stocks based on current market trends
- Parameters:
  - limit: Maximum number of recommendations to return (default: 5, max: 8)
- Notes:
  - Automatically excludes stocks already in your portfolio
  - Focuses on stocks with strong momentum and positive technical indicators
  - Response size is monitored and simplified if needed

Knowledge Graph

Query Knowledge Graph: Query the Indian stock knowledge graph for historical analysis and insights

Market Data

Get Alpha Vantage Data: Access Alpha Vantage API data for Indian stock market with free tier limitations
Search Stock Symbol: Search for Indian stock symbols by name or keywords

Technical Analysis

Get Technical Analysis: Get technical analysis indicators for an Indian stock (SMA, RSI)
- Parameters:
  - symbol: Stock symbol to analyze (e.g., "NSE:RELIANCE")
- Notes:
  - This tool requires multiple API calls to Alpha Vantage
  - May be rate limited if several analysis requests are made in quick succession
Get Optimized Technical Analysis: Smart technical analysis that avoids rate limits
- Parameters:
  - symbol: Stock symbol to analyze (e.g., "NSE:RELIANCE")
  - indicators: Comma-separated list of indicators to analyze (e.g., "SMA,RSI")
- Notes:
  - Performs preflight checks to ensure API calls are available
  - Only makes necessary API calls for requested indicators
  - Provides educational content when rate limited
  - More efficient use of the 5 calls per minute limit

API Management

Get Alpha Vantage API Status: Check current status of API calls and rate limits
- Notes:
  - Shows available API calls remaining in current minute window
  - Displays recent API call history
  - Provides recommendations on when to make calls
  - Helps Claude manage the 5 calls per minute limitation efficiently

Knowledge Graph

The server maintains a knowledge graph in MongoDB (collection: stock_knowledge_graph) that stores:

Historical analyses of Indian stocks
Performance metrics and trends for NSE and BSE listed companies
Portfolio inclusion/exclusion recommendations
Technical and fundamental insights
Indian market-specific trends and patterns

This provides Claude with persistent memory about your Indian stock portfolio and stocks of interest.

Data Optimization for Claude

This server implements several strategies to optimize data for Claude's consumption:

Automatic Data Limiting:
- Default limits on query results to prevent overwhelming Claude with too much information
- Portfolio holdings limited to 10 stocks by default (configurable up to 50)
- Recommendations limited to 5 stocks by default
- Portfolio analysis limited to 15 stocks maximum with 5 stocks per segment
Data Simplification:
- Portfolio holdings simplified to essential fields only (symbol, quantity, average price)
- Full details available when needed for analysis but hidden from direct display
- Financial data automatically compressed to focus on essential metrics
- Text fields truncated to prevent overwhelming Claude
Parameter Controls:
- Tools expose parameters to allow Claude to request more or less data as needed
- Ability to toggle between summary and detailed views
- Control over segment size and which segment to analyze
Segmented Processing:
- Portfolio analysis can be performed in segments to prevent large responses
- Each segment processes a subset of stocks (default: 5 stocks per segment)
- Allows Claude to analyze large portfolios without hitting connection timeouts
- Automatic adjustment of segment size based on analysis type
Response Size Management:
- Real-time monitoring of response size during processing
- Automatic simplification when responses exceed size thresholds
- Emergency fallback to minimal data when responses would be too large
- Detailed logging of response sizes for troubleshooting
Intelligent Internal Handling:
- Analysis functions use complete data internally while presenting simplified results
- Market trend recommendations filter out stocks already in portfolio
- Financial data compression preserves critical metrics while reducing size

These optimizations ensure Claude can process your stock data efficiently without being overwhelmed by excessive information or experiencing timeouts.

Alpha Vantage Free Tier Support

This server is optimized for Alpha Vantage's free tier API, which includes:

Rate limiting to 5 API calls per minute
Daily limit of 500 API calls
Support for key endpoints:
- GLOBAL_QUOTE - Current price information
- TIME_SERIES_DAILY - Daily price history
- OVERVIEW - Company information
- SYMBOL_SEARCH - Finding Indian stock symbols
- Basic technical indicators (SMA, RSI)

The server implements automatic rate limiting to ensure you stay within these limits.

Configuration

The server uses the following environment variables (defined in .env):

MongoDB Configuration

MONGODB_URI: MongoDB connection string (default: mongodb://localhost:27017)
MONGODB_DB_NAME: Database name (default: stock_data)
MONGODB_HOLDINGS_COLLECTION: Holdings collection name (default: holdings)
MONGODB_FINANCIALS_COLLECTION: Financials collection name (default: detailed_financials)
MONGODB_KNOWLEDGE_GRAPH_COLLECTION: Knowledge graph collection name (default: stock_knowledge_graph)

Alpha Vantage API

ALPHA_VANTAGE_API_KEY: Your Alpha Vantage API key
ALPHA_VANTAGE_BASE_URL: Alpha Vantage API URL (default: https://www.alphavantage.co/query)
ALPHA_VANTAGE_RATE_LIMIT_MINUTE: API calls allowed per minute (default: 5)
ALPHA_VANTAGE_RATE_LIMIT_DAY: API calls allowed per day (default: 500)
ALPHA_VANTAGE_DEFAULT_EXCHANGE: Default exchange for Indian stocks (default: NSE)

MCP Server Configuration

MCP_SERVER_NAME: Server name (default: stock-analysis-mcp)
MCP_SERVER_VERSION: Server version (default: 0.1.0)

Logging Configuration

LOG_LEVEL: Logging level (default: INFO)
LOG_FORMAT: Log message format

Cache Settings

CACHE_ENABLED: Enable caching (default: True)
CACHE_TTL: Cache time-to-live in seconds (default: 3600)

License

MIT License

Alpha Vantage API Management

This server includes sophisticated management of Alpha Vantage API calls to stay within free tier limits:

Rate Limit Tracking

Maintains a global counter of API calls made in each minute window
Automatically detects and handles rate limit responses from Alpha Vantage
Provides status information through the get_alpha_vantage_status tool

Smart Call Management

Preflight Checks: Before making API calls, tools check if they'll exceed rate limits
Cost-aware Processing: Each API function has an assigned "cost" to track its impact
Graceful Degradation: When rate limits are reached, tools provide static data or educational content
Targeted Calls: Technical analysis can be configured to retrieve only specific indicators

Fallback Mechanisms

When rate limited, the system provides alternative content:
- Static market data for trending stocks
- Educational content about technical indicators
- Historical data when available
- Clear messaging about when to try again

Example Usage

Here's how Claude should use the API efficiently:

Check API Status First:
- "Let me check the Alpha Vantage API status before proceeding"
- This helps plan which calls to make within the 5-call limit
Use Optimized Tools:
- "I'll use optimized technical analysis to get just the SMA indicator"
- This makes only the necessary API calls for the requested information
Batch Similar Requests:
- "Let me collect all the stock symbols first, then query them together"
- This helps avoid making redundant or unnecessary API calls
Use Static Data When Appropriate:
- "Since we're rate limited, I'll use static trend data for now"
- This provides value even when API limits are reached