Content
# Tool List
**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 cancels the front-end page and `nginx`, retains the core `services` and `utils` of the original project, and converts them into `MCP` services.
## Project Overview
This is a stock analysis service based on FastAPI-MCP, aiming to provide comprehensive data and analysis capabilities for stocks through MCP tool function interfaces, including price, rating, technical reports, and AI analysis. The 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 provides modern API interfaces as a bridge between front-end and back-end services.
## Features
- **Built on FastAPI-MCP**: Supports SSE protocol and provides powerful API interfaces.
- **Rich Stock Analysis Tools**: Provides various stock data acquisition and analysis tool functions.
- **Multi-Market Support**: Supports A-share, Hong Kong stock, US stock, 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 improve concurrent processing capabilities.
- **Streaming Response**: Supports SSE protocol to achieve real-time data stream push.
- **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**: Uses FastApiMCP library to automatically convert APIs into MCP tool functions.
## Installation
1. **Clone 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 and fill in the API key and other information.
4. **Run Service**
```bash
python main.py
```
The service will start at `http://localhost:8000`. You can also use Uvicorn to start:
```bash
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```
## Docker Installation and Running
If you want to deploy the service through Docker, you can follow these steps:
1. **Clone Repository**
```bash
git clone https://github.com/wbsu2003/stock-scanner-mcp.git
cd stock-scanner-mcp
```
2. **Build 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 Docker Container**
Run the container and map the port. Ensure that you provide necessary configuration information, such as API keys, 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 actual values.
## Main API Interfaces
The service provides the following core API interfaces:
- **Analyze a Single Stock**: `GET /stock_analyzer`
- Analyze a stock through the stock code and market type, return comprehensive information including price, rating, technical analysis, and AI analysis, and support streaming response.
- **Get Stock Price Information**: `GET /stock_price`
- Get the latest price, price change, and other basic price information of the specified stock.
- **Get Stock Technical Analysis**: `GET /stock_technical_analysis`
- Get the technical indicator analysis of the stock, including MA trend, RSI, MACD signal, Bollinger Bands, and other technical indicators.
- **Get Stock Rating**: `GET /stock_score`
- Get the comprehensive rating and investment advice of the stock.
- **Get Stock AI Analysis**: `GET /stock_ai_analysis`
- Use AI to conduct in-depth analysis of the stock, providing comprehensive analysis results including trend, risk, and target price.
## MCP Tool Functions
The FastApiMCP library will automatically register the above APIs as MCP tool functions, which can be obtained through the `/mcp` endpoint. The following are the main MCP tool functions:
1. `analyze_stock` - Analyze a single stock (corresponding to `GET /stock_analyzer` interface)
2. `get_stock_price` - Get stock price information (corresponding to `GET /stock_price` interface)
3. `get_technical_analysis` - Get stock technical analysis (corresponding to `GET /stock_technical_analysis` interface)
4. `get_stock_score` - Get stock rating (corresponding to `GET /stock_score` interface)
5. `get_ai_analysis` - Get stock AI analysis (corresponding to `GET /stock_ai_analysis` interface)
These tool functions can be directly called by large language models.
## System Architecture
The MCP service serves as a bridge between the front-end and back-end services, providing RESTful API and SSE streaming response through the FastAPI framework. It integrates the following core services:
- **StockDataProvider**: Responsible for obtaining stock data from data sources.
- **StockAnalyzerService**: Coordinates data provision, indicator calculation, rating, and AI analysis.
- **AIAnalyzer**: Calls large language model APIs for in-depth analysis.
- **TechnicalIndicator**: Calculates technical indicators.
- **StockScorer**: Scores stocks based on technical indicators.
## Technical Features
- **Asynchronous Processing**: Utilizes FastAPI and Python's asynchronous features to improve concurrent processing capabilities.
- **Streaming Response**: Supports SSE protocol to achieve real-time data stream push.
- **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**: Uses FastApiMCP library to automatically convert APIs into MCP tool functions.
## Streaming API Endpoints
The `stock_analyzer` interface (`GET /stock_analyzer`) supports streaming response. Clients can access it through standard HTTP requests and process server-sent event (SSE) streams.
The `/mcp` endpoint of FastApiMCP also provides streaming access capabilities for tool definitions.
## Health Check
You can check the service status through the `/health` endpoint:
```
http://localhost:8000/health
```
## Usage Examples
### Using Tool Functions in MCP
In the MCP client, you can use tool functions in the following way:
```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 rating
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)
```
### Access API Documentation
After the service starts, you can access the automatically generated API documentation (Swagger UI / OpenAPI) through the following link:
```
http://localhost:8000/docs
```
## Dependencies
- fastapi
- fastapi-mcp
- mcp
- akshare
- pandas
- httpx
- python-dotenv
- uvicorn
## License
MIT
More instructions:
- Blog: [Stock Analysis MCP Service stock-scanner-mcp](https://laosu.tech/2025/07/02/Stock-Analysis-MCP-Service-stock-scanner-mcp)
- 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)
