Content
# 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/), which removes the front-end page and `nginx`, retaining the core `services` and `utils` of the original project, and converting it into an `MCP` service.
## Project Overview
This is a stock analysis service based on FastAPI-MCP, designed to provide comprehensive stock-related data and analysis capabilities through MCP utility function interfaces, including price, ratings, technical reports, and AI analysis. The service integrates the stock data acquisition and analysis functionalities from the original project [https://github.com/lanzhihong6/stock-scanner](https://github.com/lanzhihong6/stock-scanner/) and provides a modern API interface, serving as a bridge between the front-end and back-end services.
## Features
- **Built on FastAPI-MCP**: Supports SSE protocol and provides powerful API interfaces.
- **Rich Stock Analysis Tools**: Offers various stock data acquisition and analysis utility functions.
- **Multi-Market Support**: Supports analysis of A-shares, Hong Kong stocks, US stocks, and fund data.
- **Integrated AI Analysis**: Combines large language models for in-depth analysis.
- **Asynchronous Processing**: Utilizes FastAPI and Python's asynchronous features to enhance concurrent processing capabilities.
- **Streaming Response**: Supports SSE protocol for real-time data stream pushing.
- **Modular Design**: Each service module has clear responsibilities, making it easy to maintain and extend.
- **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 utility 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. Ensure to provide 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="YourAPIKey" \
-e API_URL="YourAPIUrl" \
-e API_MODEL="YourLargeLanguageModel" \
stock-scanner-mcp
```
Please replace `YourAPIKey`, `YourAPIUrl`, and `YourLargeLanguageModel` with actual values.
## Main API Interfaces
The service provides the following core API interfaces:
- **Analyze a Single Stock**: `GET /stock_analyzer`
- Analyzes a stock by its code and market type, returning comprehensive information including price, ratings, technical analysis, and AI analysis, supporting streaming responses.
- **Get Stock Price Information**: `GET /stock_price`
- Retrieves the latest price, price change percentage, and other basic price information for a specified stock.
- **Get Stock Technical Analysis**: `GET /stock_technical_analysis`
- Retrieves technical indicator analysis for a stock, including MA trends, RSI, MACD signals, Bollinger Bands, and other technical indicators.
- **Get Stock Ratings**: `GET /stock_score`
- Retrieves the comprehensive rating and investment suggestions for a stock.
- **Get Stock AI Analysis**: `GET /stock_ai_analysis`
- Uses AI for in-depth analysis of a stock, providing comprehensive analysis results including trends, risks, and target price levels.
## MCP Utility Functions
The FastApiMCP library automatically registers the above APIs as MCP utility functions, which can be accessed through the `/mcp` endpoint. Here are the main MCP utility functions:
1. `analyze_stock` - Analyze a single stock (corresponds to `GET /stock_analyzer` interface)
2. `get_stock_price` - Get stock price information (corresponds to `GET /stock_price` interface)
3. `get_technical_analysis` - Get stock technical analysis (corresponds to `GET /stock_technical_analysis` interface)
4. `get_stock_score` - Get stock ratings (corresponds to `GET /stock_score` interface)
5. `get_ai_analysis` - Get stock AI analysis (corresponds to `GET /stock_ai_analysis` interface)
These utility functions can be directly called by large language models.
## System Architecture
This 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 acquiring 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 concurrent processing capabilities.
- **Streaming Response**: Supports SSE protocol for real-time data stream pushing.
- **Modular Design**: Each service module has clear responsibilities, making it easy to maintain and extend.
- **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 utility 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 FastApiMCP `/mcp` endpoint also provides streaming access capabilities for tool definitions.
## Health Check
You can check the service status via the `/health` endpoint:
```
http://localhost:8000/health
```
## Usage Examples
### Using Utility Functions in MCP
In the MCP client, you can use the utility functions as follows:
```python
import mcp
# Example: Analyze 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 ratings
score_info = await mcp.use_tool("get_stock_score", {"stock_code": "600795", "market_type": "A"})
print(score_info)
# Example: Get stock AI analysis
ai_analysis_result = await mcp.use_tool("get_ai_analysis", {"stock_code": "600795", "market_type": "A"})
print(ai_analysis_result)
```
### Accessing API Documentation
Once the service is running, 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
Further 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)
