Cyphers MCP Server
The Cyphers MCP Server enables AI assistants to access and analyze data from the Neople Cyphers game API through the Model Context Protocol.
Game Context Resources: Provides game rules, systems, terminology, meta-analysis, character lists, and role classifications through cyphers://game-context and cyphers://characters to help AI understand game data.
Player Management: Search players by nickname with partial/full match options (cy_players_search), get detailed player information by ID (cy_players_get), and retrieve match history with date range filtering and pagination (cy_players_matches).
Match Analysis: Retrieve detailed match information including teams, players, and results by match ID (cy_matches_get).
Rankings: Access rating point rankings with player search and filtering (cy_ranking_ratingpoint), character-specific rankings (cy_ranking_characters), and TSJ (투신전) tournament rankings (cy_ranking_tsj).
Items & Equipment: Search battle items by name, slot, rarity, season, or character (cy_battleitems_search), get single item details (cy_battleitems_get), and batch retrieve up to 30 items at once (cy_battleitems_multi_get).
Characters: Get a complete list of all available characters (cy_characters_list).
Image Generation: Generate character image URLs with adjustable zoom levels 1-3 (cy_images_character_url) and item image URLs (cy_images_item_url).
Performance Optimization: Automatic caching (30 seconds to 24 hours based on data type) and rate limiting compliance (100/sec, 5k/min, 300k/hour).
AI Integration: Compatible with Claude, Cursor, Cline, and other AI assistants through MCP.
Provides tools for interacting with the Neople Cyphers Open API, allowing users to search for player profiles, retrieve match histories, view rankings, and search for game items and character information for the Cyphers game.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Cyphers MCP Server search for player 'Neo' and show their recent match history"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Cyphers MCP Server (Python)
Neople Cyphers Open API를 위한 MCP (Model Context Protocol) 서버입니다.
📋 소개
이 MCP 서버는 Neople의 Cyphers Open API를 Claude, Cursor, Cline 등의 AI 어시스턴트에서 쉽게 사용할 수 있도록 합니다. 플레이어 검색, 매칭 기록 조회, 랭킹 조회, 아이템 검색 등 다양한 기능을 제공합니다.
Related MCP server: MCP Riot Server
✨ 주요 기능
📚 Resources (게임 컨텍스트)
MCP Server가 LLM에게 사이퍼즈 게임에 대한 컨텍스트를 제공합니다:
Resource URI | 설명 |
| 게임 규칙, 시스템, 용어, 메타 분석 등 |
| 캐릭터 목록, 역할 분류, 평가 지표 등 |
LLM이 API 데이터를 받았을 때 올바르게 해석하고 분석할 수 있도록 도와줍니다.
🔧 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 키 발급
애플리케이션 등록
Cyphers API 키 발급
2. 환경변수 설정
Linux/macOS:
export CYPHERS_API_KEY="your-api-key-here"Windows:
set CYPHERS_API_KEY=your-api-key-here3. 서버 실행
# 직접 실행
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 # 레이트 리밋 관리
├── docs/ # 게임 컨텍스트 문서 (MCP Resources)
│ ├── cyphers_game_context.md # 게임 규칙, 용어, 메타
│ └── characters_reference.md # 캐릭터 목록, 역할 분류
├── note/ # 프로젝트 노트
├── pyproject.toml # Python 패키지 설정
├── README.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-reinstallMCP 연결 오류
Python 버전 확인 (3.10 이상 필요)
패키지가 제대로 설치되었는지 확인
환경변수 경로가 올바른지 확인
📚 참고 자료
📄 라이선스
MIT License
👤 작성자
DHKim327
🔗 링크
Available Tools
13 toolscy_battleitems_getC
아이템 ID로 아이템 상세 정보를 조회합니다.
Inputs: itemId (required).
cy_battleitems_multi_getC
여러 아이템의 상세 정보를 한 번에 조회합니다 (최대 30개).
Inputs: itemIds (required).
cy_battleitems_searchC
아이템을 검색합니다.
Inputs: itemName, characterId, slotCode, rarityCode, +2 more.
cy_characters_listB
모든 캐릭터 목록을 조회합니다.
Inputs: no named parameters.
cy_images_character_urlC
캐릭터 이미지 URL을 생성합니다.
Inputs: characterId (required), zoom.
cy_images_item_urlC
아이템 이미지 URL을 생성합니다.
Inputs: itemId (required).
cy_matches_getC
매치 ID로 매칭 상세 정보를 조회합니다.
Inputs: matchId (required).
cy_players_getC
플레이어 ID로 플레이어 상세 정보를 조회합니다.
Inputs: playerId (required).
cy_players_matchesC
플레이어의 매칭 기록을 조회합니다.
Inputs: playerId (required), gameTypeId, startDate, endDate, +2 more.
cy_players_searchC
닉네임으로 플레이어를 검색합니다.
Inputs: nickname (required), wordType, limit.
cy_ranking_charactersC
캐릭터별 랭킹을 조회합니다.
Inputs: characterId (required), rankingType (required), offset, limit.
cy_ranking_ratingpointC
통합 랭킹(레이팅 포인트)을 조회합니다.
Inputs: playerId, nickname, offset, limit.
cy_ranking_tsjC
투신전 랭킹을 조회합니다.
Inputs: tsjType (required), offset, limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Every tool has a clearly distinct purpose with no ambiguity. Tools are organized by resource type (battleitems, characters, images, matches, players, ranking) and specific actions (get, multi_get, search, list, url, matches, ranking types), making it easy for an agent to select the correct one without confusion.
All tool names follow a consistent 'cy_resource_action' pattern using snake_case throughout. The naming convention is predictable and readable, with no deviations in style or structure across the 13 tools.
With 13 tools, the count is well-scoped for a game-related server covering items, characters, images, matches, players, and rankings. Each tool earns its place by addressing specific needs without being overwhelming or insufficient for the domain.
The tool surface provides comprehensive coverage for querying and retrieving data across multiple game domains, with minor gaps such as no update or delete operations (which may be intentional for a read-only API) and no direct character detail lookup beyond listing. Agents can work around these with the available tools.
Related MCP Connectors
An MCP server that integrates with Discord to provide AI-powered features.
MCP server for AI dialogue using various LLM models via AceDataCloud
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
Related MCP Servers
AlicenseBqualityCmaintenanceAn MCP server that enables AI assistants to interact with the Notion API, allowing them to search, read, comment on, and create content in Notion workspaces through natural language commands.19282,573 npm4,711MIT- AlicenseBqualityDmaintenanceA community-developed Model Context Protocol server that integrates with the Riot Games API to provide League of Legends data, enabling AI assistants to retrieve player information, ranked stats, champion mastery, and match summaries through natural language queries.527MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that integrates with the official Clash Royale API to provide real-time data on players, clans, cards, and tournaments. It enables users to query battle logs, chest cycles, and global rankings directly through Claude Desktop or Claude Code.-
- AlicenseNot gradedqualityDmaintenanceAn MCP server that integrates EVE Online's ESI API with AI assistants to enable natural language interaction with character data, market information, and assets. It provides 22 tools for managing skills, wallet balances, ship fittings, and more directly through AI-powered clients.2MIT