VNStock MCP Server

An MCP (Message Communication Protocol) server that fetches historical stock prices for multiple companies using the vnstock library. The server reads a configuration file and allows clients (e.g., Claude Desktop) to request stock data within a specific date range.

Features

• Fetch historical stock data for multiple Vietnamese companies
• Configure stocks to track via a JSON configuration file
• Request stock data within a specific date range
• MCP protocol support for integration with Claude Desktop
• Direct API endpoint for stock data retrieval

Requirements

• Python 3.10 or higher
• vnstock 3.2.2
• fastapi 0.115.12
• uvicorn 0.34.0
• pydantic 2.10.6
• python-dotenv 1.0.1

Installation

Using Virtual Environment (recommended)

# Create virtual environment
python -m venv venv

# Activate virtual environment (Windows)
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Using Poetry

# Install poetry if not already installed
pip install poetry

# Install dependencies
poetry install

Using UV

# Install uv if not already installed
pip install uv

# Install dependencies
uv pip install -r requirements.txt

Configuration

The application uses two separate configuration files:

1. Stock Configuration (stock_config.json)

This file contains the configuration for the stock data service, including which stocks to track and server settings:

{
  "stocks": [
    {
      "symbol": "VNM",
      "name": "Vietnam Dairy Products Joint Stock Company"
    },
    {
      "symbol": "VHM",
      "name": "Vinhomes Joint Stock Company"
    }
  ],
  "server": {
    "host": "0.0.0.0",
    "port": 8000
  },
  "default_days": 30,
  "max_days": 365
}

2. Claude Desktop Configuration (claude_desktop_config.json)

This file is used by Claude Desktop to register and communicate with the MCP server:

{
  "mcpServers": {
    "stock_prices": {
      "command": "python",
      "args": [
        "path/to/vnstock_mcp_server/main.py"
      ]
    }
  }
}

You should place this file in the Claude Desktop configuration directory, typically:

• Windows: %APPDATA%\Claude Desktop\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude Desktop/claude_desktop_config.json
• Linux: ~/.config/Claude Desktop/claude_desktop_config.json

Usage

Starting the Server

# Activate virtual environment (if using)
venv\Scripts\activate

# Start the server with default configuration
python main.py

# Start the server with custom configuration
python main.py --config path/to/config.json

# Override host and port
python main.py --host 127.0.0.1 --port 8080

API Endpoints

MCP Protocol Endpoints

• GET /get-tools: Get available tools for the MCP protocol
• POST /tool-call: Call a tool in the MCP protocol

Direct Endpoints

• GET /: Health check endpoint
• GET /stock-data: Get historical stock data for one or more symbols

Example Requests

Using the MCP Protocol

// POST /tool-call
{
  "tool": "vnstock",
  "method": "get_stock_data",
  "parameters": {
    "symbols": ["VNM", "VHM"],
    "start_date": "2023-01-01",
    "end_date": "2023-01-31"
  }
}

Using the Direct Endpoint

GET /stock-data?symbols=VNM&symbols=VHM&start_date=2023-01-01&end_date=2023-01-31

License

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