YGOCDB

This MCP server provides a set of tools to query and retrieve English and Chinese game card data from the 百鸽 ygocdb API. It supports two operating modes — STDIO for direct MCP client integration and HTTP for containerized or HTTP client access — making it convenient to power chat clients and automation with up-to-date card data.

How to use

You run the server in either STDIO mode for direct MCP clients or HTTP mode for container deployments and HTTP-based clients. STDIO is the default and well suited for desktop MCP clients, while HTTP exposes a web endpoint at port 8081 for remote access.

How to install

Prerequisites: Node.js and npm installed on your machine. You can verify by running node -v and npm -v in your terminal.

Install the MCP server globally or run directly with NPX.

# Global installation
npm install -g ygocdb-mcp-server

# Or run directly (recommended)
npx ygocdb-mcp-server

For local development, clone the project, install dependencies, build, and start in your preferred mode.

# Clone the project
git clone <repository-url>
cd ygocdb-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run STDIO mode
npm run start:stdio

# Run HTTP mode
npm run start:http

Run modes and endpoints

STDIO mode is intended for direct MCP client integration (e.g., Claude Desktop). Use this when you want in-app MCP communication without exposing an HTTP interface.

HTTP mode exposes an HTTP server that starts on port 8081. The MCP endpoint is at /mcp, so you can reach it at http://localhost:8081/mcp.

# STDIO mode command (from the project setup)
npm run start:stdio

# HTTP mode command (from the project setup)
npm run start:http

Claude Desktop integration

Add a MCP server configuration to Claude Desktop. You can choose NPX (recommended) or a local build path.

{
  "mcpServers": {
    "ygocdb": {
      "command": "npx",
      "args": ["ygocdb-mcp-server"]
    }
  }
}

If you prefer using a locally built package, specify the Node command and the path to the built entry point.

{
  "mcpServers": {
    "ygocdb": {
      "command": "node",
      "args": ["path/to/ygocdb-mcp/dist/index.js"],
      "cwd": "path/to/ygocdb-mcp"
    }
  }
}

Docker deployment

Build a Docker image and run the server in STDIO or HTTP mode depending on your deployment needs.

# Build the image
docker build -t ygocdb-mcp .

# Run STDIO mode (for integration)
docker run -i --rm ygocdb-mcp

# Run HTTP mode (for service)
docker run -p 8081:8081 ygocdb-mcp

Additional notes

The server uses cross-env to ensure environment variables are handled consistently across platforms. It supports Windows, macOS, Linux, and Docker environments. If you plan to run in Docker, the HTTP mode is typically used for service-oriented deployments.

Available tools

search_cards

Search Yu-Gi-Oh! cards by keywords, returning matching cards by name or effect text.

get_card_by_id

Fetch detailed information for a single Yu-Gi-Oh! card by its card ID.

get_card_image

Retrieve the image for a Yu-Gi-Oh! card by its card ID.