Character Details MCP

An MCP server that helps LLMs gather rich, structured information about fictional characters for storytelling and image generation.

It fetches from Fandom wikis and Wikipedia, then caches results locally (24-hour TTL) for fast follow-up responses.

Tools

Tool	Description
get_character	Fetch full character details (cached or live)
refresh_character	Force re-fetch from external sources
list_characters	List all locally cached characters
remove_character	Delete a character from the local cache
generate_image_prompt	Build a tag list for image generation tools
generate_story_context	Build a structured reference doc for roleplay/writing

Data Sources

• Fandom wikis — franchise-specific, much richer character data
• Wikipedia — supplements missing sections

Supported franchise → wiki mappings are defined in fetcher.py (FRANCHISE_WIKIS). Adding a new franchise is a one-liner.

Setup

Requirements

• Python 3.11+
• uv (recommended) or pip

Install

cd character_details
uv pip install -e .

Run (stdio transport)

uv run character-details

Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "character-details": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/character_details",
        "character-details"
      ]
    }
  }
}

Docker Deployment

A deploy.sh script is provided for easy Docker build and deployment.

Quick Start

./deploy.sh build    # Build the Docker image
./deploy.sh run      # Run the container locally

Commands

Command	Description
build	Build the Docker image
run	Run the container locally with cache volume
push	Push the image to a registry
deploy	Build and push in one step
clean	Remove local images and containers

Options

./deploy.sh build -t v1.0.0                    # Build with specific tag
./deploy.sh push -r docker.io/myuser/          # Push to Docker Hub
./deploy.sh deploy -t v1.0.0 -r ghcr.io/myuser/  # Build and push to GitHub Container Registry

Environment Variables

• IMAGE_TAG - Image tag (default: latest)
• REGISTRY - Registry prefix (e.g., "docker.io/username/")
• IMAGE_NAME - Image name (default: character-details)

Cache

Character data is cached at ~/.local/share/character_details/cache/ as JSON files. Each entry expires after 24 hours. Use refresh_character to force an update.

Project Structure

character_details/
  src/character_details/
    __init__.py
    models.py     # Pydantic data model (CharacterData)
    cache.py      # Read/write/list local JSON cache
    fetcher.py    # Fandom + Wikipedia fetching & section parsing
    server.py     # FastMCP server and tool definitions
  pyproject.toml
  README.md
  deploy.sh     # Docker build and deployment script

Test Characters

• Aerith Gainsborough — Final Fantasy VII
• Princess Peach — Super Mario
• Sucy Manbavaran — Little Witch Academia