CSMAR MCP 서버

License MCP Protocol

국태안(CSMAR) 금융 데이터베이스를 위한 Model Context Protocol (MCP) 서버로, Claude Code에서 CSMAR 금융 데이터에 직접 액세스할 수 있도록 지원합니다.

✨ 주요 기능

완벽한 CSMAR 데이터 액세스: 재무제표, 주식 거래, 기업 정보 등을 포함한 240개 이상의 데이터베이스 지원
지능형 로그인 관리: 환경 변수를 통한 자동 로그인 및 토큰 캐싱 지원
11개의 MCP 도구: 데이터베이스 탐색, 데이터 조회, 미리보기 등 모든 기능 포함
Python 미들웨어: CSMAR-PYTHON SDK 기반의 안정적인 래퍼
간편한 설정: 원클릭 설정 및 Claude Code 네이티브 통합 지원

📋 사전 요구 사항

CSMAR 계정: 유효한 CSMAR(국태안) 기관 계정
Python 3.8+: CSMAR-PYTHON SDK 설치 필요
Node.js 18+: MCP 서버 실행용
Claude Code: 최신 버전의 Claude Code 에디터

🚀 빠른 시작

1. 프로젝트 복제

git clone https://github.com/yourusername/csmar-mcp-server.git
cd csmar-mcp-server

2. 의존성 설치

npm install

3. 환경 변수 설정

설정 파일 템플릿 복사:

cp config/.env.example .env

.env 파일을 편집하여 CSMAR 계정 정보를 입력하세요:

CSMAR_API_BASE=https://api.gtarsc.com
CSMAR_API_KEY=你的API密钥（如有）
CSMAR_USERNAME=你的CSMAR用户名
CSMAR_PASSWORD=你的CSMAR密码
CSMAR_LANG=0  # 0=中文, 1=英文

4. Claude Code 설정

Claude Code 설정 파일에 MCP 서버 구성을 추가하세요:

Windows (%APPDATA%/Claude/claude_desktop_config.json): macOS/Linux (~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "csmar": {
      "command": "node",
      "args": ["/path/to/csmar-mcp-server/src/index.js"],
      "env": {
        "CSMAR_API_BASE": "https://api.gtarsc.com",
        "CSMAR_USERNAME": "你的CSMAR用户名",
        "CSMAR_PASSWORD": "你的CSMAR密码",
        "CSMAR_LANG": "0"
      }
    }
  }
}

5. Claude Code 재시작

Claude Code를 재시작하여 MCP 서버를 로드하세요.

🔧 사용 방법

설치 확인

Claude Code에서 다음을 실행하세요:

mcp__csmar__csmar_list_databases()

데이터베이스 목록이 보이면 설치가 성공한 것입니다!

기본 데이터 탐색

# 列出所有可用数据库（约240个）
mcp__csmar__csmar_list_databases()

# 查看"财务报表"数据库中的表
mcp__csmar__csmar_list_tables(database_name="财务报表")

# 查看"FS_Combas"表的字段
mcp__csmar__csmar_list_fields(table_name="FS_Combas")

# 预览表数据（前几行）
mcp__csmar__csmar_preview(table_name="FS_Combas")

데이터 조회 예시

# 查询财务报表数据
mcp__csmar__csmar_query(
    table_name="FS_Combas",
    columns=["Stkcd", "ShortName", "Accper", "Typrep", "A001000000"],
    condition="Stkcd like '3%' and Typrep='A'",
    start_time="2020-01-01",
    end_time="2021-12-31",
    limit=5
)

# 查询记录数量
mcp__csmar__csmar_query_count(
    table_name="FS_Combas",
    condition="Stkcd like '3%'",
    start_time="2020-01-01",
    end_time="2021-12-31"
)

🛠️ 사용 가능한 도구

도구 이름	설명	매개변수
`csmar_login`	CSMAR 계정 로그인	`account`, `pwd`, `lang`
`csmar_list_databases`	액세스 가능한 데이터베이스 목록	없음
`csmar_list_tables`	데이터베이스 내 테이블 목록	`database_name`
`csmar_list_fields`	테이블 내 필드 목록	`table_name`
`csmar_query`	범용 데이터 조회	`table_name`, `columns`, `condition`, `start_time`, `end_time`, `limit`, `format`
`csmar_preview`	테이블 데이터 미리보기	`table_name`
`csmar_query_count`	레코드 수 조회	`table_name`, `columns`, `condition`, `start_time`, `end_time`
`get_stock_data`	주식 거래 데이터 가져오기	`stock_code`, `start_date`, `end_date`, `frequency`
`get_financial_data`	재무 데이터 가져오기	`stock_code`, `start_date`, `end_date`, `indicators`
`get_company_info`	기업 기본 정보 가져오기	`stock_code`

📁 프로젝트 구조

csmar-mcp-server/
├── src/
│   ├── index.js              # MCP 服务器主文件
│   └── python_client.py      # Python 客户端
├── config/
│   ├── .env.example          # 环境变量示例
│   └── .mcp.json             # MCP 配置示例
├── docs/
│   ├── CSMAR_MCP_配置完成报告.md
│   ├── 快速开始指南.md
│   └── CSMAR机构账号配置指南.md
├── examples/
│   └── test_input.json       # 测试输入示例
├── package.json              # Node.js 依赖
├── README.md                 # 本文件
└── .gitignore               # Git 忽略文件

🔍 데이터베이스 추천

자주 사용하는 데이터베이스

재무제표: 财务报表, FS_Combas, FS_Comins, FS_Comscfd
주식 거래: 股票市场交易数据, 股票日行情
기업 정보: 公司基本信息, 上市公司基本信息
거시 경제: 宏观经济数据库

데이터 기간

재무제표: 2018-2022년
AI 관련 데이터: 2024-2025년
주식 거래: 실시간 업데이트

⚠️ 주의사항

조회 제한

회당 최대 20만 건: 대규모 데이터셋은 페이지네이션 조회 필요
동일 조건 30분 제한: 동일 조건의 빈번한 조회 방지
시간 형식: 반드시 "YYYY-MM-DD" 형식을 사용해야 함

페이지네이션 조회 예시

# 第1页
条件 = "Stkcd like '3%' limit 0,200000"
# 第2页
条件 = "Stkcd like '3%' limit 200000,200000"

mcp__csmar__csmar_query(
    table_name="FS_Combas",
    columns=["Stkcd", "ShortName", "Accper", "Typrep"],
    condition=条件
)

🐛 문제 해결

자주 묻는 질문

1. "MCP 서버가 응답하지 않음"

Claude Code가 재시작되었는지 확인
.mcp.json 파일 경로 확인

Python 클라이언트 수동 테스트:

echo '{"action":"list_databases","params":{}}' | python src/python_client.py

2. "데이터베이스가 존재하지 않음"

csmar_list_databases()를 사용하여 정확한 이름 확인
데이터베이스 이름에 공백이 포함되어 있는지 확인
계정에 해당 데이터베이스 액세스 권한이 있는지 확인

3. 조회 결과가 비어 있음

시간 범위가 올바른지 확인
조회 조건 구문 검증
preview()를 사용하여 데이터 형식 먼저 확인

4. CSMAR SDK 가져오기 실패

CSMAR-PYTHON SDK가 올바르게 설치되었는지 확인
Python 경로 설정 확인
src/python_client.py의 경로 설정 확인

로그 파일

CSMAR 로그: csmar-log.log
Python 클라이언트 로그: stderr을 통해 출력
MCP 서버 로그: stderr을 통해 출력

🤝 기여

이슈 및 Pull Request를 환영합니다!

프로젝트 Fork
기능 브랜치 생성 (git checkout -b feature/amazing-feature)
변경 사항 커밋 (git commit -m 'Add amazing feature')
브랜치 푸시 (git push origin feature/amazing-feature)
Pull Request 생성

📄 라이선스

본 프로젝트는 MIT 라이선스를 따릅니다. 자세한 내용은 LICENSE 파일을 확인하세요.

🙏 감사의 말

CSMAR(국태안): 금융 데이터 서비스 제공
Anthropic: Model Context Protocol 개발
Claude Code: 훌륭한 AI 프로그래밍 환경

📞 지원

CSMAR 공식 지원: service@gtadata.com, 400-888-3636
프로젝트 이슈: GitHub Issues
문서: docs/ 디렉토리의 상세 가이드 확인

💡 팁: 사용을 시작하기 전에 CSMAR 계정과 환경 변수가 올바르게 설정되었는지 확인하세요!

CSMAR MCP Server