mcp-stock-market

meetsimform/mcp-stock-market

3.2

If you are the rightful owner of mcp-stock-market and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The MCP Stock Market server is a PHP-based Model Context Protocol server that provides real-time stock market data using the Alpha Vantage API, designed for seamless integration with VS Code and other MCP-compatible clients.

Tools
5
Resources
0
Prompts
0

MCP Stock Market

A Model Context Protocol (MCP) server written in PHP that provides real-time stock market data using the Alpha Vantage API. This server is designed to integrate seamlessly with VS Code and other MCP-compatible clients.

🚀 Features

📊 Stock Market Tools

  1. get_stock_quote - Get real-time stock quotes with current price, change, and percentage
  2. search_stocks - Search for stocks by company name or symbol
  3. get_company_overview - Get detailed company information, financials, and metrics
  4. get_intraday_data - Get intraday price data with configurable intervals (1min to 60min)
  5. get_market_status - Check current market status and trading hours
  6. get_top_gainers_losers - Get top performing and worst performing stocks

🔧 Technical Features

  • Pure PHP implementation (no external dependencies)
  • JSON-RPC 2.0 protocol compliance
  • STDIO transport for VS Code integration
  • Comprehensive error handling and validation
  • Alpha Vantage API rate limit handling
  • Structured JSON responses

📋 Requirements

  • PHP 7.4+ with the following extensions:
    • json (for JSON processing)
    • curl (for HTTP requests)
  • Internet connection (for Alpha Vantage API access)
  • VS Code with MCP extension (for IDE integration)

🛠️ Installation & Setup

1. Clone or Download Files

# Navigate to your project directory
cd path/to/mcp-stock-market

2. Configure Environment Variables

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

# Edit the .env file and add your Alpha Vantage API key
# Get your free API key at: https://www.alphavantage.co/support/#api-key
nano .env

3. Test PHP Setup

php test.php

This will verify:

  • PHP version and extensions
  • File permissions
  • Environment configuration
  • Alpha Vantage API connectivity
  • JSON-RPC functionality

4. Make Server Executable

chmod +x server.php

🔌 VS Code Integration

Method 1: Using VS Code MCP Extension

  1. Open VS Code
  2. Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
  3. Search for "MCP" and select "MCP: Add Server"
  4. Configure the server:
    • Name: mcp-stock-market
    • Command: php
    • Args: ["./server.php"] (or full path to your server.php)
    • Working Directory: Your project directory path

Method 2: Manual Configuration

Add to your VS Code settings.json:

{
  "mcp.servers": {
    "mcp-stock-market": {
      "command": "php",
      "args": ["./server.php"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Method 3: Using MCP Configuration File

Use the provided mcp-config.json:

{
  "mcpServers": {
    "mcp-stock-market": {
      "command": "php",
      "args": ["./server.php"],
      "cwd": "."
    }
  }
}

📖 Usage Examples

Get Stock Quote

{
  "tool": "get_stock_quote",
  "parameters": {
    "symbol": "AAPL"
  }
}

Response:

{
  "symbol": "AAPL",
  "price": "150.25",
  "change": "+2.15",
  "changePercent": "+1.45%",
  "lastUpdated": "2025-10-07"
}

Search Stocks

{
  "tool": "search_stocks",
  "parameters": {
    "query": "Apple"
  }
}

Get Company Overview

{
  "tool": "get_company_overview",
  "parameters": {
    "symbol": "TSLA"
  }
}

Get Intraday Data

{
  "tool": "get_intraday_data",
  "parameters": {
    "symbol": "GOOGL",
    "interval": "5min"
  }
}

Get Market Status

{
  "tool": "get_market_status",
  "parameters": {}
}

Get Top Gainers/Losers

{
  "tool": "get_top_gainers_losers",
  "parameters": {}
}

🧪 Testing the Server

Manual Testing

# Start the server
php server.php

# In another terminal, send test requests
echo '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{}}}' | php server.php

Automated Testing

php test.php

⚙️ Configuration

Alpha Vantage API

  • API Key: Configured via ALPHA_VANTAGE_API_KEY environment variable (falls back to demo key if not set)
  • Base URL: https://www.alphavantage.co/query
  • Rate Limits:
    • Free: 25 requests/day
    • Standard: 75 requests/day
    • Premium: 1,200+ requests/day

Server Settings

  • Timeout: 10 seconds for API requests
  • Data Limit: 20 latest data points for intraday data
  • Error Handling: Comprehensive with proper JSON-RPC error codes

🔧 Troubleshooting

Common Issues

  1. "Extension not loaded" error

    sudo apt-get install php-curl php-json

  2. "Permission denied" error

    chmod +x server.php

  3. "API Rate Limit" error

    • Wait for rate limit reset
    • Consider upgrading Alpha Vantage plan

  4. "Connection refused" error

    • Check internet connection
    • Verify firewall settings

Debug Mode

The server logs debug information to STDERR. Monitor with:

php server.php 2> debug.log

📁 File Structure

mcp-stock-market/
├── server.php              # Main MCP server implementation
├── test.php                # Test and validation script
├── composer.json           # PHP project configuration
├── mcp-config.json         # MCP client configuration
├── claude_desktop_config.json # Claude Desktop configuration
├── .vscode/
│   ├── settings.json       # VS Code workspace settings
│   └── mcp.json           # MCP VS Code configuration
└── README.md              # This documentation

🔐 Security Considerations

✅ Security Features Implemented:

  • Environment Variables: API key is loaded from environment variables (.env file or system environment)
  • Fallback Protection: Uses demo key if no environment variable is set (with warning message)
  • Configuration Separation: Sensitive data separated from source code

⚠️ Additional Security Considerations:

  • SSL Verification: CURL SSL verification is disabled for development. Enable it for production: 
    CURLOPT_SSL_VERIFYPEER => true,
  • Authentication: No authentication is implemented. Add proper authentication for production environments.
  • Input Validation: Basic input validation is implemented. Consider enhanced validation for production use.
  • Rate Limiting: No client-side rate limiting. Implement rate limiting to avoid API quota exhaustion.

📋 Environment Setup:

# Set via environment variable
export ALPHA_VANTAGE_API_KEY="your-api-key-here"

# Or create .env file (recommended)
cp .env.example .env
# Edit .env and add your API key

📝 API Documentation

MCP Protocol Compliance

  • Protocol Version: 2024-11-05
  • Transport: STDIO
  • Format: JSON-RPC 2.0
  • Capabilities: Tools support

Error Codes

  • -32700 Parse error
  • -32601 Method not found
  • -32603 Internal error
  • Custom error codes for API-specific issues

🚀 Production Deployment

For production use, consider:

  1. Environment variables for API keys
  2. SSL certificate verification
  3. Rate limiting and caching
  4. Authentication and authorization
  5. Comprehensive logging
  6. Health checks and monitoring

📞 Support

🎯 Quick Start Checklist

  • Run php test.php to verify setup
  • Make server.php executable with chmod +x server.php
  • Add server to VS Code using Ctrl+Shift+P → "MCP: Add Server"
  • Test with a stock quote: get_stock_quote with {"symbol": "AAPL"}
  • Verify real-time data is being returned

🎉 Ready to get real-time stock data in VS Code!