ak-mcp: AKShare 금융 데이터 MCP Server

ak-mcp는 Model Context Protocol(MCP) 기반의 금융 데이터 조회 서비스로, AKShare를 데이터 소스로 사용하여 공식 데이터 사전에 수록된 1000개 이상의 데이터 인터페이스를 MCP 도구로 자동 등록하여 Claude, Codex, Cursor 등 Agent가 직접 발견하고 호출할 수 있게 합니다. 조회 결과는 기본적으로 MySQL 로컬 캐시에 저장되며, 캐시가 적중하면 원격 데이터 소스에 접근하지 않아 네트워크 의존성과 지연 시간을 크게 줄입니다.

특징

• 최신 MCP 프로토콜 준수: 공식 Python SDK v2(mcp>=2.0) 기반으로 2026-07-28 개정판 프로토콜을 구현하고, 2025-11-25 및 이전 버전 클라이언트와 자동 호환됩니다. 동일 서비스가 stdio와 Streamable HTTP 두 가지 전송 방식을 동시에 지원합니다.

• 전체 인터페이스 커버리지: 인터페이스 목록은 공식 문서(https://akshare.akfamily.xyz/data/)에서 직접 생성되며, 현재 1019개 인터페이스를 수록하여 주식, 선물, 채권, 옵션, 외환, 통화, 현물, 금리, 사모/공모 펀드, 지수, 거시경제, 암호화폐, 은행, 에너지, 대체 데이터, 툴박스, 지표 계산 등 모든 대분류를 포함합니다.

• 캐시 우선: MySQL 캐시가 적중하면 즉시 반환하고, 적중하지 않을 때만 AKShare에 원본 요청 후 캐시에 기록합니다. 원본 요청 실패 시 자동으로 만료된 데이터를 반환하고 stale: true로 표시합니다.

• 분류별 TTL: 실시간 시세, 일빈도(日頻) 히스토리, 거시경제 지표, 정적 사전에 각각 다른 캐시 유효 기간을 적용하며, 함수별 재정의를 지원합니다.

• 네이티브 파라미터 Schema: 각 도구의 파라미터는 AKShare 함수 시그니처에서 자동 생성되며(필수/선택, 타입, 기본값), Agent가 문서의 파라미터 그대로 호출할 수 있어 별도의 래핑 형식을 배울 필요가 없습니다.

• 운영 친화적: 인터페이스 검색, 캐시 통계, 캐시 정리, 헬스 체크, 캐시 우회 직접 조회 등의 메타 도구가 내장되어 있습니다.

아키텍처

flowchart LR
    A[Agent 客户端<br/>Claude / Codex / Cursor] -->|stdio 或 Streamable HTTP| M[MCP Server<br/>mcp>=2, 2026-07-28]
    M --> T[1000+ 个数据工具<br/>工具名 = AKShare 函数名]
    T --> E[执行器<br/>超时 / 参数过滤 / 结果规范化]
    E --> C{MySQL 缓存<br/>ak_cache}
    C -->|命中且未过期| R[返回 JSON]
    C -->|未命中或过期| K[AKShare]
    K --> C
    K --> D[新浪 / 东财 / 交易所等数据源]
    M --> Meta[元工具<br/>检索 / 统计 / 清理 / 健康]

디렉터리 구조

ak-mcp/
├── src/ak_mcp/               # 服务端核心代码
│   ├── server.py             # MCP 服务装配与工具注册
│   ├── registry.py           # 文档接口清单加载与安装包匹配
│   ├── schema.py             # 函数签名 -> JSON Schema
│   ├── executor.py           # 线程池调用、超时、参数过滤
│   ├── normalize.py          # DataFrame -> JSON 规范化
│   ├── cache.py              # MySQL 缓存（SQLAlchemy）
│   ├── ttl.py                # TTL 规则引擎
│   ├── config.py             # 环境变量配置
│   └── cli.py                # 命令行入口
├── scripts/
│   ├── build_registry.py     # 抓取官方文档生成接口清单
│   └── init_db.sql           # MySQL 初始化 SQL
├── config/
│   ├── akshare_registry.json # 官方文档接口清单（已生成，1019 个）
│   └── ttl_rules.yaml        # 缓存 TTL 规则
├── tests/                    # 单元与集成测试
├── docker-compose.yml        # MySQL 8 本地环境
├── pyproject.toml
└── Makefile

환경 요구 사항

• Python 3.11+(권장: 3.11/3.12/3.13)

• MySQL 8.0+(프로젝트에 포함된 Docker Compose 사용 가능)

• AKShare 공식 요구 사항: 64비트 운영체제

빠른 시작

1. 설치

make install          # 创建 .venv 并安装依赖（等价于 pip install -e ".[dev]"）

2. MySQL 시작

방법 1(권장): 프로젝트에 포함된 Docker Compose 사용:

make mysql-up         # docker compose up -d mysql，映射标准 3306 端口

방법 2: 기존 MySQL 사용, 수동으로 초기화 실행:

mysql -uroot -p < scripts/init_db.sql

3. 설정

cp .env.example .env

필요에 따라 .env를 수정합니다. 기본 설정은 프로젝트에 포함된 MySQL 컨테이너에 대응합니다:

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=ak_mcp
MYSQL_PASSWORD=ak_mcp_password
MYSQL_DB=ak_mcp

모든 설정 항목은 .env.example을 참조하세요.

4. 인터페이스 목록 생성(선택 사항)

저장소에는 이미 config/akshare_registry.json(공식 문서 1.18.94 기준)이 커밋되어 있어 일반적으로 다시 생성할 필요가 없습니다. 최신 문서와 동기화가 필요하면:

make registry

5. 서비스 시작

stdio 모드(데스크톱 클라이언트의 로컬 호출용):

ak-mcp
# 或 .venv/bin/ak-mcp

Streamable HTTP 모드(원격/다중 클라이언트 호출용):

ak-mcp --transport http --host 127.0.0.1 --port 8765

기타 명령:

ak-mcp --list-functions          # 打印全部文档接口
ak-mcp --refresh-registry        # 重新抓取官方文档并更新清单
ak-mcp --verbose                 # 调试日志

QuickStart: Agent 연동

Claude Desktop

claude_desktop_config.json(Claude Desktop의 MCP 설정)을 편집합니다:

{
  "mcpServers": {
    "ak-mcp": {
      "command": "/absolute/path/to/ak-mcp/.venv/bin/ak-mcp",
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "ak_mcp",
        "MYSQL_PASSWORD": "ak_mcp_password",
        "MYSQL_DB": "ak_mcp"
      }
    }
  }
}

저장 후 Claude Desktop을 재시작하면 대화에서 바로 stock_zh_a_hist, fund_open_fund_info_em, macro_china_cpi_yearly 등 모든 데이터 도구를 사용할 수 있습니다.

Codex

~/.codex/config.toml에 다음을 추가합니다:

[mcp_servers.ak-mcp]
command = "/absolute/path/to/ak-mcp/.venv/bin/ak-mcp"
env = { MYSQL_HOST = "127.0.0.1", MYSQL_PORT = "3306", MYSQL_USER = "ak_mcp", MYSQL_PASSWORD = "ak_mcp_password", MYSQL_DB = "ak_mcp" }

Codex CLI의 MCP 추가 명령을 사용할 수도 있습니다(구체적인 문법은 현재 Codex 버전의 codex mcp --help를 기준으로 합니다).

범용 MCP 클라이언트(HTTP)

먼저 HTTP 모드를 시작합니다:

ak-mcp --transport http --host 127.0.0.1 --port 8765

그런 다음 URL을 지원하는 MCP 클라이언트에서 설정합니다:

{
  "mcpServers": {
    "ak-mcp": {
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

사용 예시

A주(중국 주식) 히스토리 시세 조회

Agent가 도구 stock_zh_a_hist를 직접 호출하며, 파라미터는 AKShare 공식 문서와 동일합니다:

stock_zh_a_hist(symbol="000001", period="daily", start_date="20260801", end_date="20260826", adjust="")

JSON 반환:

{
  "data": [
    {
      "日期": "2026-08-03",
      "开盘": 10.38,
      "收盘": 10.47,
      "最高": 10.59,
      "最低": 10.32,
      "成交量": 886273
    }
  ],
  "meta": {
    "function": "stock_zh_a_hist",
    "params": { "symbol": "000001", "period": "daily" },
    "cached": true,
    "stale": false,
    "rows": 18,
    "elapsed_ms": 2,
    "truncated": false
  }
}

인터페이스 찾기

인터페이스 이름이 확실하지 않을 때는 먼저 ak_search_functions를 호출합니다:

ak_search_functions(query="可转债 实时行情")
ak_search_functions(category="macro")

운영 메타 도구

인터페이스 목록 메커니즘

1. scripts/build_registry.py가 공식 문서 data/ 디렉터리의 모든 페이지 Markdown 소스 파일을 가져와 接口：xxx, 描述：xxx 및 입력 파라미터 테이블을 파싱하여 config/akshare_registry.json을 생성합니다.

2. 서비스 시작 시 이 목록을 유일한 소스로 사용합니다. 목록에 수록되어 있고 설치된 akshare에 존재하는 인터페이스를 하나씩 MCP 도구로 등록합니다.

3. 목록에는 있지만 설치 패키지에 없는 인터페이스는 건너뛰고 경고를 출력합니다(예: 문서가 버전보다 먼저 릴리스된 경우). AKSHARE_REQUIRE_VERSION_MATCH=true로 버전 일치를 강제할 수 있습니다.

캐시 메커니즘

캐시 우선 흐름

1. 함수명 + 정규화된 파라미터 + akshare 버전으로 SHA-256 캐시 키를 계산합니다.

2. 적중하고 만료되지 않은 경우: 캐시 JSON을 직접 반환합니다(meta.cached = true).

3. 적중하지 않거나 만료된 경우: AKShare에 원본 요청 후 정규화하여 MySQL에 기록합니다.

4. 원본 요청 실패: 만료된 데이터가 있으면 이전 데이터를 반환하고 meta.stale = true로 표시합니다. 그렇지 않으면 오류 텍스트를 반환합니다.

테이블 구조(ak_cache)

서비스 시작 시 SQLAlchemy로 자동 생성되며, scripts/init_db.sql을 참조하여 수동 생성할 수도 있습니다:

TTL 규칙

규칙은 config/ttl_rules.yaml에 정의되며, 순서대로 매칭되고 먼저 적중한 규칙이 우선 적용됩니다:

설정 항목

개발 및 테스트

make test          # 运行全部测试（单元 + MCP 内存集成）
make lint          # ruff 检查
make fmt           # ruff 格式化

테스트 범위: 문서 파싱, Schema 생성, TTL 분류, 파라미터 정규화, 캐시 키, SQLite 캐시 동작, MCP 인메모리 모드에서의 도구 등록/호출/오류 처리. 실제 네트워크와 MySQL 통합 검증은 로컬 Docker Compose로 수동 실행할 수 있습니다 (위의 "엔드투엔드 검증" 참조).

자주 묻는 질문

시작 시 특정 인터페이스를 찾을 수 없다는 메시지: Registry function not found in installed akshare: xxx 는 공식 문서가 현재 설치된 akshare 버전보다 먼저 릴리스되었음을 의미하며, 해당 인터페이스는 건너뛰고 다른 인터페이스에는 영향을 주지 않습니다. akshare를 업그레이드하거나 목록을 다시 생성하면 됩니다.

MySQL 연결 실패: .env의 포트가 docker compose ps에 표시된 것과 일치하는지 확인하세요(이 프로젝트 컨테이너는 표준 포트 3306을 직접 매핑합니다). 또는 AK_CACHE_ALLOW_DEGRADED=true를 설정하여 임시로 캐시 없는 모드로 시작할 수 있습니다.

데이터 소스 인터페이스 오류: AKShare의 일부 인터페이스는 제3자 웹사이트(신랑(新浪), 동재(东财) 등)에 의존하므로 네트워크, 리스크 관리 또는 필드 변경의 영향을 받을 수 있습니다. ak_execute_raw로 캐시를 우회하여 재현하거나 akshare 버전을 업그레이드할 수 있습니다.

시간대와 인코딩: 캐시 시간은 UTC로 통일됩니다. 데이터 쓰기와 읽기는 UTF-8/utf8mb4를 사용하며, 중국어 컬럼명도 그대로 반환할 수 있습니다.

보안 및 프로덕션 권장 사항

• v1은 로컬 및 내부 네트워크를 대상으로 하며 인증과 속도 제한이 내장되어 있지 않습니다. 프로덕션 환경에서는 게이트웨이 뒤에 배치하는 것을 권장합니다(OAuth/API Key, 속도 제한).

• 캐시는 모든 Agent가 공유하며 사용자를 구분하지 않습니다. 민감한 시나리오에서는 별도의 격리를 추가하세요.

• HTTP 모드를 외부에 노출할 때는 내부 네트워크 주소만 수신하거나 리버스 프록시로 TLS를 추가하는 것을 권장합니다.

License

MIT