character-mcp/USER_GUIDE.md

Character Details MCP — User Guide

An MCP server that fetches structured information about fictional characters from Fandom wikis and Wikipedia, making it easy for LLMs to accurately portray or generate content for characters from games, anime, and other media.

---

Quick Start (Docker — recommended)

1. Build the image

cd character_details
docker build -t character-details-mcp .

2. Add to Claude Desktop

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

{
  "mcpServers": {
    "character-details": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "character-details-cache:/root/.local/share/character_details",
        "character-details-mcp"
      ]
    }
  }
}

Restart Claude Desktop. The server will appear in the tools list.

Important flags:

• -i — keeps stdin open (required for stdio MCP transport)
• --rm — removes the container after the session ends
• -v character-details-cache:... — named Docker volume so the cache persists across sessions

---

Quick Start (Local Python)

Requirements

• Python 3.11+
• uv

Install

cd character_details
uv venv && uv pip install -e .

Add to Claude Desktop

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

---

Tool Reference

get_character

Fetches complete character data. Checks the local cache first (24-hour TTL), fetches live if stale.

Parameters:

Name	Type	Description
name	string	Character name, e.g. "Aerith Gainsborough"
franchise	string	Franchise name, e.g. "Final Fantasy VII"

Returns: Formatted markdown with Description, Appearance, Personality, Background, Abilities, Relationships, and source URLs.

Example prompt:

Use get_character to look up Aerith Gainsborough from Final Fantasy VII, then write a short scene where she tends her flowers.

---

refresh_character

Same as get_character but bypasses the cache and re-fetches from source.

Use when: You suspect the cached data is incomplete, or you want the latest wiki content.

---

list_characters

Lists all characters currently in the local cache with their franchise and cache timestamp.

---

remove_character

Deletes a specific character from the cache.

Parameters: name, franchise

---

get_character_from_url

Fetches character data from a specific URL you provide. Fandom wiki URLs are detected automatically and processed with the same structured extraction as get_character, giving richer results. Non-Fandom URLs are scraped generically.

Parameters:

Name	Type	Description
url	string	Full URL to the character page
name	string	Character name (optional — inferred from the page title for Fandom URLs)
franchise	string	Franchise name (optional)

Example prompt:

Use get_character_from_url to fetch data from https://finalfantasy.fandom.com/wiki/Tifa_Lockhart

When to use instead of get_character:

• The character's wiki page isn't found by the automatic search
• You want data from a specific page (e.g. a particular version or alternate wiki)
• The franchise isn't in the supported list and you have a direct Fandom URL
• You have a non-Fandom source you want to pull from

---

generate_image_prompt

Builds a comma-separated tag list for image generation tools (Stable Diffusion, Midjourney, DALL-E, etc.).

Parameters:

Name	Type	Description
name	string	Character name
franchise	string	Franchise name
style	string	Art style hint (optional), e.g. "anime", "oil painting", "pixel art"
scene	string	Scene description (optional), e.g. "in a flower field", "battle pose"
extra_tags	string	Comma-separated additional tags (optional)

Example prompt:

Use generate_image_prompt for Princess Peach (Super Mario) in an anime style, standing in her castle throne room.

---

generate_story_context

Produces a structured reference document for roleplay or creative writing. Includes overview, personality, background, appearance, abilities, and relationships.

Parameters:

Name	Type	Description
name	string	Character name
franchise	string	Franchise name
scenario	string	Current scenario to include (optional)
include_abilities	boolean	Whether to include abilities section (default: true)

Example prompt:

Use generate_story_context for Sucy Manbavaran from Little Witch Academia. The scenario is: she's been asked to teach a potions class after the regular teacher falls ill.

---

Supported Franchises

The following franchises have a dedicated Fandom wiki mapped for richer data:

Franchise	Wiki	Aliases
Final Fantasy (I–XVI)	finalfantasy.fandom.com	final fantasy 1–16, ffi–ffxvi, ff1–ff16
Super Mario	mario.fandom.com	mario, super mario
Little Witch Academia	little-witch-academia.fandom.com	lwa
Uma Musume	umamusume.fandom.com	uma musume pretty derby
Fire Emblem	fireemblem.fandom.com
Senran Kagura	senrankagura.fandom.com
Vocaloid	vocaloid.fandom.com
Dragon Ball	dragonball.fandom.com	dragon ball z, dbz, dragon ball super, dbs
League of Legends	leagueoflegends.fandom.com	lol
Street Fighter	streetfighter.fandom.com
Sonic	sonic.fandom.com	sonic the hedgehog
Spy x Family	spy-x-family.fandom.com	spy family, spyxfamily
The Legend of Zelda	zelda.fandom.com	zelda, legend of zelda
The Witcher	witcher.fandom.com	witcher
Metroid	metroid.fandom.com
Pokemon	pokemon.fandom.com	pokémon

Characters from other franchises will still work using Wikipedia as the data source. The data will be less detailed but usable.

---

Adding a New Franchise

Open src/character_details/fetcher.py and add an entry to FRANCHISE_WIKIS:

FRANCHISE_WIKIS: dict[str, str] = {
    # existing entries ...
    "my hero academia": "myheroacademia",   # maps to myheroacademia.fandom.com
    "mha": "myheroacademia",
}

The value is the Fandom community subdomain (the part before .fandom.com). You can find it by visiting the character's wiki and noting the URL.

After editing, rebuild the Docker image:

docker build -t character-details-mcp .

---

Cache

• Location: ~/.local/share/character_details/cache/ (host) or the character-details-cache Docker volume
• Format: one JSON file per character
• TTL: 24 hours — expired entries are re-fetched automatically
• Manual clear: use remove_character tool, or delete the JSON files / volume directly

---

Using with the Claude API / SDK

If you're building an application with the Anthropic SDK rather than Claude Desktop, start the server in stdio mode and connect it as an MCP server:

import anthropic

client = anthropic.Anthropic()

# Point to the server command
server_params = {
    "command": "docker",
    "args": [
        "run", "--rm", "-i",
        "-v", "character-details-cache:/root/.local/share/character_details",
        "character-details-mcp"
    ]
}

See the MCP Python SDK docs for full integration examples.

---

Troubleshooting

No data returned / all fields empty

• Check internet connectivity from inside the container: docker run --rm character-details-mcp python -c "import httpx; import asyncio; asyncio.run(httpx.AsyncClient().get('https://en.wikipedia.org'))"
• Some franchises don't have a Fandom wiki mapped — add one (see above)

Stale or incorrect data

• Use refresh_character to bypass the cache
• Or delete the cached file from the volume

Claude Desktop doesn't show the server

• Verify the JSON config is valid (no trailing commas)
• Confirm the image name matches exactly: character-details-mcp
• Check Claude Desktop logs: ~/Library/Logs/Claude/