Us Stock MCP Server

🚀 US Stock Data MCP Service

A Model Context Protocol (MCP) server designed for accessing and updating historical price data of US stocks.

🚀 Quick Start

This is a Model Context Protocol (MCP) server tailored for accessing and updating historical price data of US stocks.

✨ Features

• Local Data Storage: Stock data is stored locally in CSV format for quick access.
• Automatic Update: Supports automatic retrieval of stock data from Yahoo Finance.
• Safe Data Writing: Uses temporary files to ensure atomicity and security of data writing.
• Flexible Time Range: Allows customization of the start date for data updates.

📦 Installation

1. Ensure Python 3.x is installed.
2. Clone this repository.
3. Install dependencies:

pip install -r requirements.txt

💻 Usage Examples

Basic Usage

1. Start the Server

python server.py

The default data storage path after startup is: ~/Library/Application Support/us-market-data/data. You can customize the data storage path via the US_STOCK_DATA_DIR environment variable.

2. Available Functions

MCP Tools

• get_local_stock_data:

  • Function: Retrieve local historical stock data.
  • Parameters:
    • symbol: Stock symbol, e.g., 'AAPL', 'MSFT'.

• update_stock_data:

  • Function: Update stock data.
  • Parameters:
    • symbol: Stock symbol, e.g., 'AAPL', 'MSFT'.
    • start_date: Start date in the format YYYY - MM - DD, default is 2015 - 01 - 01.

MCP Resources

• Resource URI: usstock://{symbol}/historical
  • Function: Provide local historical price data of US stocks.
  • Parameters:
    • symbol: Stock symbol.

📚 Documentation

Data Format

The stored stock data includes the following fields:

• Date: Trading date.
• Open: Opening price.
• High: Highest price.
• Low: Lowest price.
• Close: Closing price.
• Volume: Trading volume.

Dependencies

• mcp: MCP protocol implementation.
• pandas: Data processing and analysis.
• yfinance: Yahoo Finance data retrieval.
• pydantic: Data validation and settings management.

🔧 Technical Details

Notes

1. Duplicate data is automatically handled during the update process, keeping the latest records.
2. A 5 - second delay is implemented to avoid frequent API requests.
3. Error handling is included in all data operations to ensure service stability.