# a-stock-data-mcp

MCP Server adapter for [simonlin1212/a-stock-data](https://github.com/simonlin1212/a-stock-data).

The upstream project is kept as a pinned Git submodule under `vendor/a-stock-data`.
This project does not rewrite upstream A-share data-fetching logic; it exposes that logic through
FastMCP tools, prompts, and resources.

## Install

```bash
git submodule update --init --recursive
uv sync
cp .env.example .env
```

## Run

```bash
uv run python -m mcp_server.server
```

The server uses stdio. SSE and Streamable HTTP are intentionally left as future entrypoints.

## Claude Desktop

```json
{
  "mcpServers": {
    "a-stock-data": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/a-stock-data-mcp",
        "run",
        "python",
        "-m",
        "mcp_server.server"
      ]
    }
  }
}
```

## Cursor

Add the same command to Cursor MCP settings:

```json
{
  "mcpServers": {
    "a-stock-data": {
      "command": "uv",
      "args": ["--directory", "/path/to/a-stock-data-mcp", "run", "python", "-m", "mcp_server.server"]
    }
  }
}
```

## VS Code

```json
{
  "servers": {
    "a-stock-data": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/path/to/a-stock-data-mcp", "run", "python", "-m", "mcp_server.server"]
    }
  }
}
```

## Cherry Studio

Use a stdio MCP server:

- Command: `uv`
- Args: `--directory /path/to/a-stock-data-mcp run python -m mcp_server.server`

## Tools

- Stock: `search_stock`, `get_stock_quote`, `get_stock_basic`, `get_stock_news`,
  `get_stock_notice`, `get_stock_report`
- K-line: `get_daily_kline`, `get_weekly_kline`, `get_monthly_kline`, `get_minute_kline`
- Finance: `get_finance`, `get_income_statement`, `get_balance_sheet`, `get_cashflow`,
  `get_eps`, `get_roe`, `get_pe`, `get_pb`
- Sector: `get_industry`, `get_concept`, `get_industry_members`, `get_concept_members`
- Hot: `get_hot_rank`, `get_limit_up_pool`, `get_limit_down_pool`, `get_broken_limit`,
  `get_hot_concepts`
- Dragon tiger: `get_dragon_tiger`
- Money: `get_money_flow`, `get_main_force`, `get_north_money`
- ETF: `get_etf`, `get_etf_components`
- Index: `get_index_quote`, `get_index_kline`
- Notice and research: `get_notice`, `get_research_report`
- Analysis: `analyze_stock`, `analyze_market`

All tools return:

```json
{"success": true, "data": {}}
```

or:

```json
{"success": false, "error": "...", "message": "..."}
```

## Prompts

- `analyze_stock`
- `daily_market_summary`
- `analyze_sector`
- `today_hot_stock`

## Resources

- `market://calendar`
- `market://industry`
- `market://concept`
- `market://index`
- `market://exchange`
- `market://etf`

## Configuration

`.env` supports:

- `LOG_LEVEL`
- `REQUEST_TIMEOUT`
- `ENABLE_CACHE`
- `CACHE_TTL_QUOTE`
- `CACHE_TTL_NEWS`
- `CACHE_TTL_FINANCE`
- `CACHE_TTL_SECTOR`
- `USER_AGENT`

## Development

```bash
uv run pytest
uv run ruff check .
uv run black --check .
uv run mypy .
```

## Notes

`a-stock-data` currently publishes a Markdown Skill rather than a Python package. The adapter extracts
allowlisted Python definitions from `SKILL.md` and ignores examples/top-level calls.

`mootdx` is not installed by default because current `mcp` and `mootdx` releases have incompatible
`httpx` dependency pins. Quote/news/finance/sector tools run without it; K-line tools are registered
and fail with a clear dependency message until upstream publishes a compatible dependency set.

Some requested MCP tools, such as ETF components or board member lists, have no exact upstream helper
today. They are registered and return structured status instead of adding new scrapers outside the
adapter boundary.