Skip to main content
Glama
deenesjakoruzh
yli769227-jpg

ashare-mcp

by yli769227-jpg
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

ashare-mcp

Convierte los informes financieros de acciones A en herramientas que tu LLM puede llamar. An MCP server that turns Chinese A-share financial statements into tools your LLM can call.

Permite que Claude (o cualquier cliente MCP) obtenga directamente el balance general, el estado de resultados y el estado de flujo de efectivo estructurados con una sola frase como "¿Cómo estuvo el informe anual de 2024 del Ping An Bank?", con campos seleccionados, unidades claras y optimizado para caché.

Fuente de datos: East Money, a través de akshare, todo gratuito y sin necesidad de token.

¿Por qué crear otro?

La mayoría de los proyectos de "LLM financiero" en GitHub se centran en trading agents y RAG de 10-K de la SEC: los primeros están muy homogeneizados y los segundos solo sirven para acciones estadounidenses. La combinación de Acciones A + Chino + protocolo MCP es casi inexistente.

El posicionamiento de ashare-mcp es muy específico: hacer una sola cosa, los informes financieros de acciones A, y hacerlo de manera que cualquier cliente LLM pueda integrarlo en diez segundos. No predice precios de acciones, no escribe informes de investigación, no toma decisiones por ti; simplemente traslada los datos de East Money a las llamadas de herramientas del LLM, con campos limpios, unidades claras y errores definidos.

Related MCP server: sfc-data-mcp

Inicio rápido

git clone https://github.com/yli769227-jpg/ashare-mcp.git
cd ashare-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

Ejecuta una prueba de humo:

python -c "from ashare_mcp.data_source import get_annual_statements; \
  r = get_annual_statements('SZ000001', 2024); \
  print(r['company_name'], r['balance_sheet']['TOTAL_ASSETS'])"
# -> 平安银行 5769270000000.0

Integración con Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json (Mac):

{
  "mcpServers": {
    "ashare": {
      "command": "/absolute/path/to/ashare-mcp/.venv/bin/python",
      "args": ["-m", "ashare_mcp.server"]
    }
  }
}

Reinicia Claude Desktop y podrás preguntar directamente:

Ayúdame a revisar el informe anual de 2024 del Ping An Bank, ¿cuáles son sus activos totales, pasivos totales, beneficio neto y flujo de caja operativo?

Lista de herramientas

Herramienta

Entrada

Salida

get_three_statements

stock_code, year

Tres estados financieros anuales (~150 campos seleccionados)

cross_check_balance

stock_code, year

Resultados de 3 comprobaciones cruzadas + error + específico de la industria

compare_peers

stock_codes[], year, metrics?

Comparación horizontal de N empresas + ranking / max-min-avg-std + ROE

El código admite de forma normalizada múltiples formatos como 000001 / SZ000001 / sz.000001 / 000001.SZ.

cross_check_balance incluye actualmente 4 comprobaciones (las 3 primeras son genéricas de la industria, la 4ª es consciente de la industria):

  1. Equilibrio del balance — TOTAL_ASSETS = TOTAL_LIABILITIES + TOTAL_EQUITY

  2. Identidad de flujo de caja — NETCASH_OPERATE + NETCASH_INVEST + NETCASH_FINANCE + RATE_CHANGE_EFFECT = CCE_ADD

  3. Conciliación de efectivo final/inicial — END_CCE − BEGIN_CCE = CCE_ADD

  4. Desglose del beneficio operativo (consciente de la industria)

    • Bancos: OPERATE_PROFIT = OPERATE_INCOME − OPERATE_EXPENSE

    • Empresas industriales/comerciales: OPERATE_PROFIT = TOTAL_OPERATE_INCOME − TOTAL_OPERATE_COST + OTHER_INCOME + INVEST_INCOME + FAIRVALUE_CHANGE_INCOME + ASSET_IMPAIRMENT_INCOME + CREDIT_IMPAIRMENT_INCOME + ASSET_DISPOSAL_INCOME [+ EXCHANGE_INCOME]

    • Identificación automática de industria: Si ACCEPT_DEPOSIT > 1 mil millones, usa la fórmula bancaria; si tiene TOTAL_OPERATE_INCOME + TOTAL_OPERATE_COST, usa la fórmula industrial; de lo contrario, skipped (seguros, etc., no soportados por ahora).

Tolerancia: 10,000 RMB para las 3 primeras (redondeo de partidas individuales), 10,000,000 RMB para la 4ª (acumulación de redondeo de múltiples partidas). Si faltan campos o la industria no se puede identificar, esa comprobación se marca como skipped, sin afectar a las demás. En pruebas reales, 4 empresas de 3 industrias (bancos / baijiu / baterías) pasaron las 4/4 comprobaciones en sus informes de 2024.

Uso de caché LRU: si llamas a get_three_statements antes de cross_check_balance, esta última responde en < 1ms (los datos de la misma acción ya están en memoria).

Métricas predeterminadas de compare_peers: TOTAL_ASSETS / TOTAL_OPERATE_INCOME / PARENT_NETPROFIT / NETCASH_OPERATE / TOTAL_EQUITY, deriva automáticamente ROE = PARENT_NETPROFIT / Capital promedio (promedio del capital al final del año actual y del año anterior; los datos del año anterior se obtienen de la caché LRU sin costo; si faltan datos del año anterior, se degrada al capital final, marcado en el campo roe_method como ending_equity_fallback). Fallback automático: si falta TOTAL_OPERATE_INCOME en la banca, retrocede a OPERATE_INCOME y se marca en el campo fallbacks. Implementación concurrente: ThreadPoolExecutor (max_workers=8), extracción paralela para N empresas (si una falla, no afecta al resto, se registra en errors). En pruebas, la comparación de los 4 grandes bancos en 2024 se completó en ~38s; el ROE de China Merchants Bank fue del 12.85% (líder a largo plazo en banca minorista).

Arquitectura

flowchart LR
    LLM[Claude / 任意 MCP 客户端] -->|JSON-RPC over stdio| Server[ashare-mcp<br/>FastMCP server]
    Server -->|代码归一化| Norm[股票代码归一化<br/>SZ/SH/BJ 自动判断]
    Server -->|拉取三表| DS[数据源封装<br/>akshare 包装层]
    DS -->|缓存命中| Cache[(进程内存缓存<br/>lru_cache)]
    DS -->|缓存未命中| YearlyEM[akshare<br/>by_yearly_em]
    YearlyEM -->|HTTP| EM[东方财富<br/>财报数据接口]
    DS -->|字段过滤| Filter[剔除元数据列<br/>剔除同比列<br/>剔除空/零字段]
    Server -->|结构化 JSON| LLM

Diseño clave:

  • Nombres de campos conservan el inglés original de East Money (TOTAL_ASSETS / LOAN_ADVANCE / NETPROFIT). El LLM puede entenderlos directamente, y los campos de diferentes industrias (bancos / industriales / seguros) están en el mismo diccionario, sin necesidad de juicios de industria.

  • Caché en memoria del proceso hace que la "comparación de varios años de la misma empresa" sea casi gratuita: el arranque en frío carga todo, los cambios de año posteriores son < 1ms.

  • Los registros van a stderr, sin contaminar el canal del protocolo MCP stdio.

Hoja de ruta

Versión

Herramienta

Estado

v0

get_three_statements

✅

v1

cross_check_balance (3 comprobaciones genéricas)

✅

v1

compare_peers (comparación horizontal + ROE derivado)

✅

v1.5 (actual)

cross_check_balance + desglose de beneficio operativo (consciente de la industria)

✅

v1.5 (actual)

compare_peers actualizado a ROE_avg (capital promedio)

✅

v2

Herramienta de tendencia interanual track_company_history (varios años + CAGR)

Pendiente

v2

Datos trimestrales + métricas derivadas interanuales/secuenciales

Pendiente

v2

Publicación en el registro oficial de MCP

Pendiente

Desarrollo local

# 增量验证(每次改完跑一遍)
python -c "from ashare_mcp.utils import normalize_stock_code; \
  assert normalize_stock_code('000001') == 'SZ000001'"

python -c "from ashare_mcp.server import mcp; \
  import asyncio; print([t.name for t in asyncio.run(mcp.list_tools())])"

Declaración de datos

  • Fuente de datos: East Money, a través de akshare.

  • La latencia, el alcance y la precisión de los datos dependen de East Money, no constituyen asesoramiento de inversión.

  • Solo para fines educativos y de investigación.

Licencia

MIT — ver LICENSE.

Available Tools

3 tools
compare_peersA

同业 N 家公司同年年报横向对比,自动算排名 / 最大最小 / 均值 / 标准差,加派生指标 ROE。

参数: stock_codes: 公司代码列表,如 ['000001', '600036', '601398']。建议 2-10 家。 支持各种格式:'000001' / 'SZ000001' / 'sz.000001' / '000001.SZ'。 year: 年份。 metrics: 可选,自定义对比字段。默认包括: TOTAL_ASSETS / TOTAL_OPERATE_INCOME / PARENT_NETPROFIT / NETCASH_OPERATE / TOTAL_EQUITY。 派生指标 ROE = PARENT_NETPROFIT / TOTAL_EQUITY 总是会算上。 银行业 TOTAL_OPERATE_INCOME 缺失时自动 fallback 到 OPERATE_INCOME(在 fallbacks 字段里标注)。

返回: { "year": 2024, "report_date": "2024-12-31", "metrics": ["TOTAL_ASSETS", ..., "ROE"], "companies": [ { "stock_code": "SZ000001", "company_name": "平安银行", "values": {metric: number}, "ranks": {metric: rank}, # 1 = 最大 "fallbacks": {original_key: actual_key} | null } ], "summary": { metric: {"max", "min", "avg", "std", "count"} }, "errors": [ {"stock_code": "...", "error": "..."} # 单家失败不挂整体 ] }

并发实现: ThreadPoolExecutor(max_workers=8),N 家公司并行拉。 缓存联动: 已经查过的公司走 lru cache,< 1ms 复用。

ParametersJSON Schema
NameRequiredDescriptionDefault
stock_codesYes
yearYes
metricsNo

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses concurrency (ThreadPoolExecutor with 8 workers), caching (lru cache), single-failure tolerance, and fallback logic for bank metrics. Return structure is detailed with example JSON.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear sections for parameters, return fields, and implementation details. Every sentence adds value without redundancy. Length is appropriate for a complex tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, yet description provides complete return structure with example JSON, concurrency, caching, and error handling. Covers all behavioral aspects needed for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 0% coverage, but description fully explains stock_codes formats, year, metrics default and optional, and derived ROE. Provides examples and constraints, compensating completely for schema gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it compares annual reports of N peer companies horizontally, computes ranks, min/max, mean, std, and derived ROE. It distinguishes from siblings like cross_check_balance and get_three_statements by specifying peer comparison logic.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly recommends 2-10 companies, describes default metrics, and explains derived ROE always included. It doesn't explicitly state when not to use or alternatives, but provides clear context for appropriate use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

cross_check_balanceA

跑财务勾稽校验,检测三大表数据是否互相自洽。返回每条校验的 passed/failed/skipped 状态与误差。

参数: stock_code: A 股代码,支持多种格式(同 get_three_statements)。 year: 年份,如 2024。仅支持年报。

返回: { "stock_code": "SZ000001", "company_name": "平安银行", "report_date": "2024-12-31", "checks": [ { "name": "balance_sheet_equation", "label": "资产负债平衡", "formula": "TOTAL_ASSETS = TOTAL_LIABILITIES + TOTAL_EQUITY", "lhs_value": 5769270000000.0, "rhs_value": 5769270000000.0, "diff": 0.0, "tolerance": 10000.0, "status": "passed" }, ... ], "summary": {"total": 3, "passed": 3, "failed": 0, "skipped": 0} }

当前 v1 包含 3 条行业通用勾稽:

  1. 资产负债平衡: TOTAL_ASSETS = TOTAL_LIABILITIES + TOTAL_EQUITY

  2. 现金流恒等式: 三大现金流 + 汇率影响 = 现金净增加额

  3. 期末/期初现金对账: END_CCE - BEGIN_CCE = CCE_ADD

容忍度 1 万元(财报舍入)。字段缺失时该条 status='skipped',不影响其它校验。

ParametersJSON Schema
NameRequiredDescriptionDefault
stock_codeYes
yearYes

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations given, but description fully covers behavior: checks three specific equations with tolerance, returns passed/failed/skipped status, handles missing fields gracefully, and notes annual-only support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with intro, parameter details, return format example, and list of checks. Every sentence is informative and no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, description provides full return example and explains all statuses and tolerance. Parameter semantics are fully covered, and sibling references add context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds significant meaning beyond schema: explains stock_code format and links to sibling tool, clarifies year only supports annual reports, and includes example values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool performs financial cross-check validation among three statements, distinguishing it from siblings like get_three_statements and compare_peers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides parameter specifics (stock_code supports multiple formats, year only annual reports) and lists the three checks. Does not explicitly exclude use cases, but context suffices.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_three_statementsA

拉取 A 股某只股票某年的年报三大财务报表(资产负债表 / 利润表 / 现金流量表)。

参数: stock_code: A 股代码,支持多种格式 —— '000001' / 'SZ000001' / 'sz.000001' / '000001.SZ'。 year: 年份(整数),如 2024。仅支持年报(报告期 12-31)。

返回: { "stock_code": "SZ000001", "company_name": "平安银行", "report_date": "2024-12-31", "currency": "CNY", "unit": "yuan (元)", "balance_sheet": {...}, # 字段如 TOTAL_ASSETS / LOAN_ADVANCE / ACCEPT_DEPOSIT "income_statement": {...}, # 字段如 OPERATE_INCOME / NETPROFIT / PARENT_NETPROFIT "cash_flow_statement": {...}, # 字段如 NETCASH_OPERATE / NETCASH_INVEST / NETCASH_FINANCE }

数据源: 东方财富(via akshare)。字段名为东方财富原始英文(SCREAMING_SNAKE_CASE)。 单位: 人民币元。 缓存: 进程内存缓存,同一只股票多次查询(不同年份)只走一次网络。

ParametersJSON Schema
NameRequiredDescriptionDefault
stock_codeYes
yearYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full weight. It discloses caching behavior, data source, currency, unit, and field naming conventions, but does not mention authentication or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a brief intro, bullet points for parameters, and a clear return format, though it could be slightly more concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and lack of output schema, the description covers all relevant aspects: purpose, parameters, return structure, data source, caching, and units, making it fully informative.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description adds crucial detail: multiple accepted formats for stock_code and the requirement that year be an integer for annual reports only.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (拉取/fetch), resource (年报三大财务报表), and scope (A股某只股票某年), distinguishing it from sibling tools like compare_peers and cross_check_balance.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description specifies that only annual reports are supported and provides parameter formats, but does not explicitly compare to sibling tools or state when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedcompare_peers
    • First observedcross_check_balance
    • First observedget_three_statements
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clear, distinct purpose: retrieving financial statements, cross-checking consistency, and comparing peers. There is no overlap or ambiguity.

Naming Consistency5/5

All tool names follow a consistent snake_case verb_noun pattern (compare_peers, cross_check_balance, get_three_statements), making them predictable and clear.

Tool Count4/5

Three tools is minimal but sufficient for the focused domain of A-share annual financial analysis. The count feels well-scoped without being overly thin.

Completeness4/5

The tools cover core workflows: data retrieval, internal consistency checks, and peer comparison. Minor gaps like quarterly data or individual ratio lookups exist, but the surface is largely complete for annual report analysis.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • sfc-data-mcp

    yangxinagfeng123
    F
    license
    Not graded
    quality
    D
    maintenance
    MCP server that wraps SFC financial data API into 32 tools for comprehensive A-share market data, including real-time quotes, rankings, limit-up statistics, news, themes, financials, charts, research reports, and watchlists.
    -

  • ashare-mcp

    lolifamily
    A
    license
    A
    quality
    C
    maintenance
    A-share market data MCP server via baostock. Full-stack coverage: K-line, financials, DCF/DDM/PEG valuation, 11 technical indicators with proper split-day volume handling (OBV/MFI on raw bars), CN-style KDJ (J=3K-2D), risk metrics (Beta/Sharpe/MaxDD with stock-suspension-aware aligned returns), and PBoC macro data.
    25
    11
    MIT

  • @lmdat/cafef-financial-mcp

    lmdat
    A
    license
    A
    quality
    D
    maintenance
    MCP server to fetch Vietnamese corporate financial reports (balance sheet, income statement, cash flow) from cafef.vn using public API, no PDF or OCR needed.
    3
    4 npm
    1
    MIT