Cyphers

You run a Python-based MCP server that exposes Cyphers Open API endpoints so AI assistants can search players, view matches, check rankings, and look up items and images. It translates Cyphers data into a protocol-friendly format that your assistants can query efficiently.

How to use

You will run the MCP server locally or in your environment and connect your MCP client to it. The server is designed to be invoked as a Python module and will expose endpoints such as player search, player details, matches, rankings, item search and details, character lists, and image URL generation. Your MCP client can then request these endpoints to retrieve Cyphers Open API data for your assistants.

How to install

Prerequisites you need on your system:

• Python 3.10 or later
• pip or uv
• Git

# 1. Clone the server repository
git clone https://github.com/DHKim327/CyphersMCPServer.git
cd CyphersMCPServer

# 2. Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# 3. Install the MCP server package in editable mode
pip install -e .

# Optional developer dependencies
pip install -e ".[dev]"

Configuration and startup

Before you can start, you need an API key from Neople for Cyphers API access. Set the API key as an environment variable and start the server.

export CYPHERS_API_KEY="your-api-key-here"  # Linux/macOS
set CYPHERS_API_KEY=your-api-key-here        # Windows

# Start the MCP server
python -m cyphers_mcp.server
# or after installation
cyphers-mcp

Running the server with explicit command

If you prefer to start directly via Python module invocation, use this exact command.

python -m cyphers_mcp.server

Notes on usage

The server reads CYPHERS_API_KEY from your environment and serves as an MCP endpoint provider for Cursor, Claude, Cline, and other assistants. Ensure your MCP client is configured to connect to the local runtime or to the HTTP endpoint if you expose it. The server handles data from Cyphers Open API and applies caching and rate limiting as described in its capabilities.

Examples of available endpoints

The MCP server implements a range of tools to access Cyphers data, including player information, matches, rankings, items, characters, and images.

Available tools

cy_players_search

Search for a Cyphers player by nickname and retrieve matching results.

cy_players_get

Fetch detailed information for a specific Cyphers player using their ID or account details.

cy_players_matches

Retrieve a player's match history with relevant statistics and metadata.

cy_matches_get

Get detailed information about a specific match, including participants and outcomes.

cy_ranking_ratingpoint

Query the integrated ranking across players and characters by rating points.

cy_ranking_characters

Retrieve character-specific rankings and standings.

cy_ranking_tsj

Fetch rankings for 투신전 (TSJ) mode with applicable filters.

cy_battleitems_search

Search for battle items by name or attributes.

cy_battleitems_get

Get detailed information about a specific item.

cy_battleitems_multi_get

Retrieve multiple items in one request (up to 30 items).

cy_characters_list

List all available Cyphers characters.

cy_images_character_url

Generate URL for a character image.

cy_images_item_url

Generate URL for an item image.