Morningstar China MCP

简体中文 | English

An MCP server for querying Morningstar China fund data. It supports fund search, screening, latest day-end ranking, performance, portfolio, fees, managers, ownership, strategy, documents, and market data.

Features

• 15 read-only MCP tools

• 216 allowlisted fund screener fields

• Current rolling returns from the latest trading day's dayEnd data

• Fund, category, and benchmark performance comparisons

• Portfolio allocation, holdings, fixed-income exposure, fees, managers, and ownership

• Stateless per-request token isolation

• Bounded pagination, concurrency, response size, and time-series output

• HTTP and Morningstar business-status validation

Related MCP server: Stock Data MCP Server

Requirements

• Node.js 20 or later

• npm

• A valid Morningstar China JWT obtained through an authorized Morningstar session

• An MCP client that supports Streamable HTTP and custom request headers

Install and run

npm install
npm run build
npm start

The server listens on the loopback interface by default:

MCP endpoint:  http://127.0.0.1:3845/mcp
Health check:  http://127.0.0.1:3845/health

Set a different host or port when needed:

MCP_HOST=127.0.0.1 MCP_PORT=4000 npm start

MCP_PORT must be an integer from 1 to 65535. Keep the default loopback binding for local use. Put remote deployments behind HTTPS, authentication, request-size limits, and a trusted reverse proxy.

Authentication

The X-Morningstar-Token header is optional for connection setup, tools/list, and tools backed by Morningstar endpoints that currently allow anonymous access:

X-Morningstar-Token: <morningstar-jwt>

screen_funds and rank_funds_day_end require the header. The other 13 tools can be discovered and called without it while their upstream Morningstar endpoints remain public. If Morningstar later protects one of those endpoints, the tool will return the upstream authentication error.

When supplied, the server maps the value to Morningstar's custom token header. It creates a separate stateless MCP server and Morningstar client for each HTTP request, so concurrent callers do not share tokens.

The server does not acquire, refresh, persist, or log tokens. An expired supplied token receives HTTP 401. A protected tool called without a token returns an MCP AUTH_REQUIRED tool error.

MCP client configuration

Start the HTTP server, then add the following Streamable HTTP server configuration to your MCP client:

{
  "mcpServers": {
    "morningstar-cn": {
      "url": "http://127.0.0.1:3845/mcp",
      "headers": {
        "X-Morningstar-Token": "${MORNINGSTAR_TOKEN}"
      }
    }
  }
}

The headers block is optional if you only need tool discovery or anonymous tools. Set MORNINGSTAR_TOKEN in the MCP client's environment when using the two protected screening tools. The client resolves the variable and sends its value as an HTTP request header; the MCP server process does not receive it as an environment variable.

Do not place a real token directly in a committed configuration file. The client must support Streamable HTTP, custom request headers configured through headers, and environment-variable interpolation; if its configuration format differs, use the equivalent endpoint and header settings.

Tools

All tools advertise the MCP readOnlyHint. The server does not expose watch-list, portfolio, template, feedback, or account mutations.

Usage examples

Inspect one fund

{
  "code": "002276",
  "sections": ["dayEnd", "monthEnd", "rating", "risk"]
}

Call get_fund_performance with these arguments.

Discover screener fields

Before building filters, call list_screener_fields:

{
  "query": "晨星评级"
}

Then pass valid fields to screen_funds:

{
  "filters": {
    "rating3Y": ["5"],
    "returnYTD_M": ">5"
  },
  "pageSize": 20,
  "sortBy": "returnYTD_M",
  "orderBy": "desc"
}

The server rejects unknown filter and sort fields before it sends a request to Morningstar.

Rank bond funds with latest day-end data

{
  "category": "pureBond",
  "periods": ["M1", "M6", "Y1"],
  "candidateLimit": 60,
  "limit": 10,
  "minFundSize": "1",
  "inceptionYears": "3",
  "purchasableOnly": true
}

Call rank_funds_day_end with these arguments. Supported categories are pureBond, shortBond, rateBond, creditBond, ordinaryBond, activeBond, and convertibleBond.

Morningstar's bulk screener exposes month-end return fields only. This tool uses those fields to form a bounded candidate pool, then fetches each candidate's latest performance.dayEnd data and ranks the funds by their category percentiles. It minimizes the worst percentile across the selected periods, followed by the average percentile.

Return-period semantics

Morningstar uses different conventions for current and standardized research data:

• dayEnd uses rolling periods ending on the latest available trading day.

• monthEnd uses the most recent completed month-end.

• dayEnd values for Y3, Y5, and Y10 are cumulative returns.

• Long-period monthEnd values are annualized returns.

Do not compare a cumulative dayEnd.Y3 value directly with an annualized monthEnd.Y3 value. Use dayEnd for current momentum and monthEnd for consistent cross-sectional research.

Development

npm run dev        # run the TypeScript source
npm run typecheck  # strict TypeScript check
npm test           # run Vitest once
npm run build      # compile to dist/
npm run check      # typecheck, test, and build