Futures Analysis MCP Demo

Domestic Futures Analytics + MCP Tooling

A lightweight domestic futures analytics workflow built with Python, AKShare, and MCP (Model Context Protocol). Designed as a 2-3 hour project demo for a financial data analyst internship interview.

Key design points:

• Core analytics does not depend on an LLM.

• MCP exposes analytics capabilities as standardized tools.

• A future MCP-compatible Agent Client can reuse these tools.

Why This Project

This project demonstrates a complete financial data analysis workflow, from data ingestion to visualization:

1. Financial Data Ingestion — Historical main-continuous futures data via AKShare

2. Data Quality — Structured quality checks for OHLC data integrity

3. Analytics — Returns, volatility, drawdown, moving averages, volume activity

4. MCP Tooling — Standardized tool exposure via Model Context Protocol

5. Visualization — Streamlit dashboard + A4 printable report

6. Resilience — Local CSV fallback when network is unavailable

Related MCP server: A股实时行情MCP服务器

Architecture

flowchart LR
    A[Market Data<br/>AKShare / CSV] --> B[Data Service]
    B --> C[Data Quality]
    C --> D[Indicator Engine]
    D --> E[Analyzer]
    
    E --> F[MCP Server]
    E --> G[CLI Demo]
    E --> H[Streamlit UI]
    E --> I[Printable Report]

Dependency direction:

         Python Core (src/)
         ↑           ↑
         │           │
    MCP Server    Streamlit

Both MCP Server and Streamlit depend on Python Core — never the reverse. This keeps the architecture clean and the client layer replaceable.

Features

• AKShare Integration — Historical daily domestic futures data from Sina Finance

• CSV Fallback — Automatic local data fallback on network failure

• Data Quality Checks — Missing values, duplicates, OHLC constraint violations

• Financial Metrics — Cumulative return, annualized volatility, maximum drawdown

• Moving Averages — MA5 and MA20 (true SMA: requires full window before first value)

• Volume Activity — Short-term vs. medium-term volume ratio

• MCP Tools — 4 standardized tools via Model Context Protocol

• Streamlit Dashboard — Interactive web UI for analysis

• A4 Printable Report — PNG + PDF landscape financial data dashboard

• Markdown Report — Structured analysis report with quality and metrics

Supported Instruments

Project Structure

futures-analysis-mcp/
│
├── README.md                  # Project documentation
├── requirements.txt           # Python dependencies
├── .gitignore
├── demo.py                    # CLI demo entry point
├── app.py                     # Streamlit dashboard
├── generate_print_report.py   # A4 printable report generator
├── pytest.ini                 # Pytest configuration
│
├── data/                      # Local CSV fallback data
│   ├── README.md
│   ├── sample_AU.csv
│   ├── sample_RB.csv
│   └── sample_SC.csv
│
├── src/                       # Core analytics library
│   ├── __init__.py
│   ├── data_service.py        # AKShare fetch + CSV fallback
│   ├── data_quality.py        # OHLC data quality checks
│   ├── indicators.py          # Financial indicators
│   ├── analyzer.py            # Integrated market analysis
│   ├── report.py              # Markdown report generation
│   └── visualization.py       # Matplotlib A4 report charts
│
├── mcp_server/                # MCP server module
│   ├── __init__.py
│   └── server.py              # MCP tool definitions & handlers
│
├── outputs/                   # Generated outputs
│   ├── charts/
│   ├── reports/               # Markdown reports
│   └── print/                 # A4 PNG + PDF reports
│
└── tests/                     # Pytest test suite (30 tests)
    ├── test_data_quality.py
    ├── test_indicators.py
    ├── test_fallback.py
    └── test_mcp_server.py     # MCP client-server integration tests

Installation

Prerequisites

• Python 3.10 or higher

• Windows / macOS / Linux

Setup (Windows PowerShell)

# Clone or navigate to project directory
cd E:\job\projects\jinrong\futures-analysis-mcp

# Create virtual environment (recommended)
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# Install dependencies
pip install -r requirements.txt

Setup (macOS / Linux)

cd futures-analysis-mcp
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Quick Start

# Default: AU, 60 trading days
python demo.py

# Custom instrument and window
python demo.py --symbol AU --days 60
python demo.py --symbol RB --days 120
python demo.py --symbol SC --days 20

Sample output:

==================================================
  Domestic Futures Market Analysis
==================================================

Instrument: Gold Futures (AU)
Window: 60 trading days

[1/4] Loading market data...
  OK 60 records loaded
  Source: AKShare

[2/4] Checking data quality...
  OK PASS

[3/4] Calculating metrics...

  Latest Close                 936.76
  Cumulative Return             -6.73%
  Annualized Volatility         22.82%
  Maximum Drawdown            -13.40%
  MA5                          909.44
  MA20                         892.00
  Volume Ratio                   1.40

[4/4] Report generated
  outputs/reports/AU_60d_report.md

==================================================
  Descriptive analytics only. No investment advice.
==================================================

Streamlit Dashboard

streamlit run app.py

Opens an interactive dashboard with:

• Key metric cards (Close, Return, Volatility, Drawdown)

• Price & MA line chart

• Daily return bar chart

• Drawdown area chart

• Data quality overview

• Market observation text

MCP Server

The MCP server exposes 4 tools following the Model Context Protocol. It uses the official MCP Python SDK v2.0.0.

Start the server

python -m mcp_server.server

MCP Tools

All tools validate symbol (AU/RB/SC) and days (20/60/120) parameters and return clear error messages on invalid input.

Tool input examples

{
  "symbol": "AU",
  "days": 60
}

Configuration for MCP Client

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "futures-analysis": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "E:/job/projects/jinrong/futures-analysis-mcp"
    }
  }
}

Printable Report

Generate an A4 landscape financial data dashboard ready for print:

python generate_print_report.py --symbol AU --days 60

Outputs:

• outputs/print/AU_60d_analysis.png (200 DPI)

• outputs/print/AU_60d_analysis.pdf (vector)

The printable page contains only financial data visualizations:

1. Close Price + MA5 + MA20 line chart

2. Daily Return bar chart

3. Drawdown area chart

4. Volume bar chart

5. Key metric cards and data quality summary

Running Tests

pytest -v

Test coverage (30 tests):

• test_data_quality.py — Normal OHLC, high < low, negative prices, missing values, duplicates, empty data

• test_indicators.py — Daily return, cumulative return, max drawdown, moving average, volume activity, volatility, MA NaN behavior

• test_fallback.py — AKShare failure fallback, CSV column integrity, AKShare success path, input validation

• test_mcp_server.py — MCP client-server integration: tool discovery, all 4 tool calls, error handling, sequential calls

Financial Metrics

Note: 252 trading days is used as a conventional annualization assumption for this demonstration. Actual futures market trading days may vary slightly by market and year.

Data Fallback

Try AKShare  →  Success?  →  Return data (source: "AKShare")
     │
     ↓ Fail
Load Local CSV  →  Success?  →  Return data (source: "Local CSV Fallback")
     │
     ↓ Fail
Raise RuntimeError with details from both attempts

The system will never silently fail. It always reports which data source was used.

Sample CSV files contain real market data downloaded from AKShare, not synthetic/random data.

Design Decisions

Why No LLM Dependency

This project is designed as a MCP-ready financial analytics workflow, not an AI agent. It exposes standardized tools that any MCP-compatible client (including LLM-based clients) can consume. The core analytics are deterministic, testable, and auditable.

Why MCP Is Separated from Core Analytics

Following separation of concerns:

• src/ contains pure Python business logic

• mcp_server/ wraps that logic into MCP tools

• app.py (Streamlit) is a separate UI layer

This means any layer can be replaced independently.

Why No Trading Signals

This project is descriptive analytics, not predictive modeling. All observations are statistical descriptions of historical data. It does not and should not be interpreted as investment advice.

Limitations

• This project uses historical/continuous futures data for analytics demonstration.

• Continuous/main contract series may contain contract-roll effects (price gaps at roll dates).

• The system does not model transaction costs, slippage, execution latency, margin requirements, or contract-specific trading rules.

• No backtesting framework is included.

• No price prediction is performed.

• No investment advice is provided.

• Only 3 instruments (AU, RB, SC) are supported for simplicity.

• Lookback windows are limited to 20, 60, and 120 trading days.

Future Work

• LLM-based MCP Client integration

• Cross-asset comparison analysis

• Contract roll adjustment

• Backtesting framework

• Additional instruments

• Correlation analysis between instruments