OliveiraGustavo01/dbz-mcp-server

DBZ MCP Server - POC

A Model Context Protocol (MCP) server that provides access to Dragon Ball Z universe data through the Dragon Ball API.

Author

Oliveira Gustavo (@OliveiraGustavo01)

What This Does

It provides:

• Character Search: Find detailed information about Dragon Ball characters including their stats, race, affiliation, and power levels
• Planet Search: Discover Dragon Ball planets and their current status
• Transformation Search: Look up Dragon Ball transformations and their power levels
• Resource Access: Browse all available characters and planets through MCP resources

TechStack

• TypeScript - Main programming language
• Node.js - Runtime environment
• Model Context Protocol SDK - MCP server implementation
• Axios - HTTP client for API requests
• Zod - Schema validation and type safety
• Express - Web framework (dependency)
• Dragon Ball API - External data source (https://dragonball-api.com/api)

Prerequisites

• Node.js (v16 or higher)
• npm (comes with Node.js)

Installation & Setup

1. Clone or download the project (if not already done)

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Testing with MCP Inspector

# Use the MCP inspector to test the server
npm run inspector

Available Tools

The server provides three main tools:

1. Search Characters

• Tool ID: search_characters
• Description: Search for Dragon Ball characters by name

2. Search Planets

• Tool ID: search_planets
• Description: Search for Dragon Ball planets by name

3. Search Transformations

• Tool ID: search_transformations
• Description: Search for Dragon Ball transformations by name

Available Resources

• All Characters (dbz://characters) - Access to all Dragon Ball characters
• All Planets (dbz://planets) - Access to all Dragon Ball planets

🔌 Using with MCP Clients

Example Configuration (Claude Desktop)

{
  "mcpServers": {
    "dbz-mcp-server": {
      "command": "node",
      "args": ["path/to/dbz-mcp-server/build/index.js"]
    }
  }
}

Example Configuration (VSCode Copilot)

1. Create a .vscode directory
2. Create an "mcp.json" file

{
  "mcpServers": {
    "dbz-mcp-server": {
      "command": "node",
      "args": ["path/to/dbz-mcp-server/build/index.js"]
    }
  }
}

Project Structure

dbz-mcp-server/
├── src/
│   ├── index.ts          # Main server implementation
│   └── types.ts          # TypeScript type definitions
├── build/                # Compiled JavaScript output
├── package.json          # Project dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md            # Project documentation

🔗 External Dependencies

• Dragon Ball API - Provides the Dragon Ball universe data
• Model Context Protocol - Communication standard for AI assistants

Note: This project is for study and development purposes. The Dragon Ball API URL is currently hardcoded but should ideally be set as an environment variable in production environments.