stock-scanner-mcp

# Stock Analysis MCP Service **What is mcp-stock-scanner?** > `mcp-stock-scanner` is a secondary development based on the project [https://github.com/lanzhihong6/stock-scanner](https://github.com/lanzhihong6/stock-scanner/), removing the front-end page and `nginx`, while retaining the core `services` and `utils` of the original project, transforming it into an `MCP` service. ## Project Overview This is a stock analysis service based on FastAPI-MCP, designed to provide comprehensive data and analysis capabilities related to stocks through the MCP tool function interface, including price, ratings, technical reports, and AI analysis. This service integrates the stock data acquisition and analysis functions from the original project [https://github.com/lanzhihong6/stock-scanner](https://github.com/lanzhihong6/stock-scanner/) and offers a modern API interface, serving as a bridge between the front-end and back-end services. ## Features - **Built on FastAPI-MCP**: Supports the SSE protocol and provides powerful API interfaces. - **Rich Stock Analysis Tools**: Offers various functions for stock data retrieval and analysis. - **Multi-Market Support**: Supports A-shares, Hong Kong stocks, US stocks, and fund data analysis. - **Integrated AI Analysis**: Combines large language models for in-depth analysis. - **Asynchronous Processing**: Utilizes FastAPI and Python's asynchronous features to enhance concurrency capabilities. - **Streaming Response**: Supports the SSE protocol for real-time data stream pushing. - **Modular Design**: Each service module has clear responsibilities, making it easy to maintain and expand. - **Dependency Injection**: Simplifies code structure using FastAPI's dependency injection system. - **Comprehensive Error Handling**: Includes detailed exception capture and error response mechanisms. - **MCP Tool Integration**: Automatically converts APIs into MCP tool functions using the FastApiMCP library. ## Installation 1. **Clone the repository** ```bash git clone https://github.com/wbsu2003/stock-scanner-mcp.git cd stock-scanner-mcp ``` 2. **Install dependencies** ```bash pip install -r requirements.txt ``` 3. **Configure environment variables** Copy the `.env.example` file to `.env` and fill in the relevant configurations: ```bash cp .env.example .env ``` Edit the `.env` file to fill in the API key and other information. 4. **Run the service** ```bash python main.py ``` The service will start at `http://localhost:8000`. You can also start it using Uvicorn: ```bash uvicorn main:app --host 0.0.0.0 --port 8000 --reload ``` ## Docker Installation and Running If you wish to deploy the service via Docker, you can follow these steps: 1. **Clone the Repository** ```bash git clone https://github.com/wbsu2003/stock-scanner-mcp.git cd stock-scanner-mcp ``` 2. **Build the Docker Image** Execute the following command in the project root directory to build the Docker image: ```bash docker build -t stock-scanner-mcp . ``` 3. **Run the Docker Container** Run the container and map the ports. Please ensure to provide the necessary configuration information, such as the API key, either through environment variables (`-e`) or by mounting the `.env` file. ```bash docker run -d -p 8000:8000 --name stock-scanner-mcp-app \ -e API_KEY="Your API Key" \ -e API_URL="Your API URL" \ -e API_MODEL="Your Large Language Model" \ stock-scanner-mcp ``` Please replace `Your API Key`, `Your API URL`, and `Your Large Language Model` with the actual values. ## Main API Interfaces The service provides the following core API interfaces: - **Analyze a Single Stock**: `GET /stock_analyzer` - Analyze a stock using its stock code and market type, returning comprehensive information including price, rating, technical analysis, and AI analysis, with support for streaming responses. - **Get Stock Price Information**: `GET /stock_price` - Retrieve the latest price, price change percentage, and other basic price information for a specified stock. - **Get Stock Technical Analysis**: `GET /stock_technical_analysis` - Obtain technical indicator analysis for a stock, including MA trend, RSI, MACD signals, Bollinger Bands, and other technical indicators. - **Get Stock Rating**: `GET /stock_score` - Get the overall rating and investment advice for a stock. - **Get Stock AI Analysis**: `GET /stock_ai_analysis` - Perform in-depth analysis of a stock using AI, providing comprehensive analysis results including trends, risks, and target price levels. ## MCP Tool Functions The FastApiMCP library automatically registers the above APIs as MCP tool functions, which can be accessed through the `/mcp` endpoint. Here are the main MCP tool functions: 1. `analyze_stock` - Analyze a single stock (corresponds to the `GET /stock_analyzer` interface) 2. `get_stock_price` - Retrieve stock price information (corresponds to the `GET /stock_price` interface) 3. `get_technical_analysis` - Obtain stock technical analysis (corresponds to the `GET /stock_technical_analysis` interface) 4. `get_stock_score` - Get stock score (corresponds to the `GET /stock_score` interface) 5. `get_ai_analysis` - Get stock AI analysis (corresponds to the `GET /stock_ai_analysis` interface) These tool functions can be directly called by large language models. ## System Architecture The MCP service acts as a bridge between the front-end and back-end services, providing RESTful APIs and SSE streaming responses through the FastAPI framework. It integrates the following core services: - **StockDataProvider**: Responsible for fetching stock data from data sources. - **StockAnalyzerService**: Coordinates data provision, indicator calculation, scoring, and AI analysis. - **AIAnalyzer**: Calls large language model APIs for in-depth analysis. - **TechnicalIndicator**: Calculates technical indicators. - **StockScorer**: Scores based on technical indicators. ## Technical Features - **Asynchronous Processing**: Utilizes FastAPI and Python's asynchronous features to enhance concurrency capabilities. - **Streaming Response**: Supports the SSE (Server-Sent Events) protocol for real-time data stream pushing. - **Modular Design**: Each service module has clear responsibilities, making it easy to maintain and expand. - **Dependency Injection**: Uses FastAPI's dependency injection system to simplify code structure. - **Comprehensive Error Handling**: Includes detailed exception capture and error response mechanisms. - **MCP Tool Integration**: Automatically converts APIs into MCP tool functions using the FastApiMCP library. ## Streaming API Endpoint The `stock_analyzer` interface (`GET /stock_analyzer`) supports streaming responses, allowing clients to access it via standard HTTP requests and handle server-sent events (SSE) streams. The `/mcp` endpoint of FastApiMCP also provides the capability for streaming access defined by tools. ## Health Check You can check the service status via the `/health` endpoint: ``` http://localhost:8000/health ``` ## Usage Example ### Using Utility Functions in MCP In the MCP client, utility functions can be used as follows: ```python import mcp ``` # Example: Analyzing a Single Stock (Streaming Response) async for chunk in mcp.use_tool("analyze_stock", {"stock_code": "600795", "market_type": "A"}): print(chunk) # Example: Get Stock Price Information price_info = await mcp.use_tool("get_stock_price", {"stock_code": "600795", "market_type": "A"}) print(price_info) # Example: Get Stock Technical Analysis tech_analysis = await mcp.use_tool("get_technical_analysis", {"stock_code": "600795", "market_type": "A"}) print(tech_analysis) # Example: Get Stock Score score_info = await mcp.use_tool("get_stock_score", {"stock_code": "600795", "market_type": "A"}) print(score_info) # Example: Get Stock AI Analysis ```python ai_analysis_result = await mcp.use_tool("get_ai_analysis", {"stock_code": "600795", "market_type": "A"}) print(ai_analysis_result) ``` ### Accessing the API Documentation Once the service is started, you can access the automatically generated API documentation (Swagger UI / OpenAPI) via the following link: ``` http://localhost:8000/docs ``` ## Dependencies - fastapi - fastapi-mcp - mcp - akshare - pandas - httpx - python-dotenv - uvicorn ## License MIT More information: - Blog: [Stock Analysis MCP Service stock-scanner-mcp](https://laosu.tech/2025/07/02/股票分析MCP服务stock-scanner-mcp) - WeChat Official Account: [Stock Analysis MCP Service stock-scanner-mcp](https://mp.weixin.qq.com/s/x60X3th9Doqm891_sUia1A) - CSDN: [Stock Analysis MCP Service stock-scanner-mcp](https://blog.csdn.net/wbsu2004/article/details/149063663)