Cyphers MCP Server (Python)
Neople Cyphers Open API를 위한 MCP (Model Context Protocol) 서버입니다.
📋 소개
이 MCP 서버는 Neople의 Cyphers Open API를 Claude, Cursor, Cline 등의 AI 어시스턴트에서 쉽게 사용할 수 있도록 합니다. 플레이어 검색, 매칭 기록 조회, 랭킹 조회, 아이템 검색 등 다양한 기능을 제공합니다.
✨ 주요 기능
Player Tools
cy_players_search- 닉네임으로 플레이어 검색cy_players_get- 플레이어 상세 정보 조회cy_players_matches- 플레이어 매칭 기록 조회
Match Tools
cy_matches_get- 매치 상세 정보 조회
Ranking Tools
cy_ranking_ratingpoint- 통합 랭킹 조회cy_ranking_characters- 캐릭터별 랭킹 조회cy_ranking_tsj- 투신전 랭킹 조회
Item Tools
cy_battleitems_search- 아이템 검색cy_battleitems_get- 아이템 상세 조회cy_battleitems_multi_get- 여러 아이템 한번에 조회 (최대 30개)
Character Tools
cy_characters_list- 모든 캐릭터 목록 조회
Image Tools
cy_images_character_url- 캐릭터 이미지 URL 생성cy_images_item_url- 아이템 이미지 URL 생성
🚀 설치
필수 요구사항
- Python 3.10 이상
- pip 또는 uv
설치 방법
# 저장소 클론
git clone https://github.com/DHKim327/CyphersMCPServer.git
cd CyphersMCPServer
# venv 환경 생성 및 활성화
python3 -m venv .venv
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows
# 의존성 설치
pip install -e .
개발 의존성 설치
pip install -e ".[dev]"
⚙️ 설정
1. API 키 발급
- Neople Developers에 가입
- 애플리케이션 등록
- Cyphers API 키 발급
2. 환경변수 설정
Linux/macOS:
export CYPHERS_API_KEY="your-api-key-here"
Windows:
set CYPHERS_API_KEY=your-api-key-here
3. 서버 실행
# 직접 실행
python -m cyphers_mcp.server
# 또는 설치 후 명령어로 실행
cyphers-mcp
🔧 MCP 클라이언트 설정
Cursor 설정
Cursor 설정 파일에 추가:
macOS/Linux: ~/.cursor/mcp.json
Windows: %APPDATA%\Cursor\mcp.json
{
"mcpServers": {
"cyphers": {
"command": "python",
"args": ["-m", "cyphers_mcp.server"],
"cwd": "/path/to/CyphersMCPServer",
"env": {
"CYPHERS_API_KEY": "your-api-key-here"
}
}
}
}
Claude Desktop 설정
Claude Desktop 설정 파일에 추가:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"cyphers": {
"command": "python",
"args": ["-m", "cyphers_mcp.server"],
"cwd": "/home/kdhadsfasdf/CyphersMCPServer",
"env": {
"CYPHERS_API_KEY": "your-api-key-here"
}
}
}
}
Cline (VS Code Extension) 설정
- VS Code에서 Cline 확장 설치
- Cline 설정 열기
- MCP 서버 추가:
- 명령:
python -m cyphers_mcp.server - 환경변수:
CYPHERS_API_KEY=your-api-key-here
- 명령:
📖 사용 예시
플레이어 검색
닉네임 "플레이어이름"으로 사이퍼즈 플레이어를 검색해줘
최근 전적 조회
플레이어 ID "xxx"의 최근 10경기를 조회하고 승률을 분석해줘
랭킹 조회
현재 레이팅 상위 10명의 랭킹을 보여줘
🏗️ 프로젝트 구조
CyphersMCPServer/
├── cyphers_mcp/
│ ├── __init__.py # 패키지 초기화
│ ├── server.py # MCP 서버 메인
│ ├── api_client.py # Cyphers API 클라이언트
│ ├── types.py # 타입 정의
│ ├── cache.py # 캐싱 관리
│ └── rate_limiter.py # 레이트 리밋 관리
├── note/ # 프로젝트 노트
├── pyproject.toml # Python 패키지 설정
├── README.md # 이 문서
├── INSTALLATION.md # 상세 설치 가이드
├── INTRODUCTION.md # 프로젝트 소개
├── DETAIL.md # 상세 기술 문서
└── smithery.json # Smithery 배포 설정
🔧 고급 기능
캐싱
서버는 자동으로 응답을 캐싱하여 API 호출을 최적화합니다:
- 캐릭터 목록: 24시간
- 아이템 상세: 6시간
- 플레이어 정보: 5분
- 랭킹: 1분
- 매치 기록: 30초
레이트 리밋
Neople API의 레이트 리밋을 준수하기 위해 자동으로 요청을 제한합니다:
- 초당 최대 100건 (보수적 설정)
- 분당 최대 5,000건
- 시간당 최대 300,000건
🐛 문제 해결
API 키 오류
Error: CYPHERS_API_KEY environment variable is required
→ 환경변수 CYPHERS_API_KEY가 설정되었는지 확인하세요.
의존성 오류
# 의존성 재설치
pip install -e . --force-reinstall
MCP 연결 오류
- Python 버전 확인 (3.10 이상 필요)
- 패키지가 제대로 설치되었는지 확인
- 환경변수 경로가 올바른지 확인
📚 참고 자료
📄 라이선스
MIT License
👤 작성자
DHKim327
