character-mcp 0.3.11

Filesystem-backed character data server for MCP clients

Character MCP

When interacting with AI, I enjoy shaping the interactions through a character. I feel it balances out the behaviours and makes my time with AI more enjoyable. While playing around with OpenClaw, I found that even with memories and other systems, getting a somewhat consistent character to exist was rather fluid. Not all details were properly recalled and it was always unpleasant to discover what part of my little helper had sunk into the morass today. So I figured it was time to get them a little helper MCP to keep things clear and clean. And it turns out, that didn't exist yet! Which is how this project came to be. With great thanks to Codex and Claude, and my little group of characters on top. It's still early days, experimental times for the project, but it works with stability and good results. I hope you enjoy it as much as I do :) And of course, contributions are very welcome. ~ Gert

What's new in 0.3.11

• Bundled example dataset: a complete fictional dataset (Amara, Felix, Sable at the Lantern Quarter Night Market) ships with the package. Load it on any fresh install with the new load_example_dataset tool.
• Empty-dataset onboarding: get_dataset_status now surfaces load_example_dataset in next_actions and explains the option when the root is empty.
• Asset breadcrumb hints (0.3.10): four contextual hints fire at the right moment — record URL provenance when adding a local file, set a newly added image as canonical, surface add_asset_reference when no images exist, prompt to localize remote-only refs after setting them as canonical.
• Local asset storage (0.3.9): add_asset_reference copies local files into the dataset and downloads URLs locally by default. New localize_asset_reference tool pulls URL-only refs into local storage. Files over 500 MB require confirm_large=True. Asset IDs are auto-generated from the filename slug, collisions resolved with a numeric suffix.

Full changelog →

Overview

Character MCP is a server that exposes structured character, place, and object data to any MCP-compatible client. Originally built for OpenClaw, it works with Claude, Cursor, or any other MCP host.

This repository is not the live character database. It produces an installable package through GitLab CI. Real character data lives outside this repo and is mounted or configured at runtime.

The design goal is simple:

• keep the authoritative data human-editable
• keep the MCP contract narrow and predictable for agents
• keep the package code separate from user-owned data
• keep binary assets and personal data out of the release repo by default
• allow controlled writes only through explicit, validated tool paths

Current Features

• File-based entity store with entity.yaml plus markdown facets
• Entity types: character, place, object
• JSON Schema validation and type-aware integrity checks, including thin/placeholder facet warnings
• Read tools for summaries, facets, relationships, related entities, doctor, and rescan
• Guarded write tools for entity creation and narrow updates, with stricter place/object creation rules
• Broad character bucket facets like wardrobe and rituals are rejected at write time
• Dataset cleanup tool for quarantining orphan entity directories and pruning stale facet references
• Backup + validate + rollback write safety model
• Polling watcher for automatic rescans
• FastMCP server adapter compatible with any MCP client
• Tool-call trace file for auditing MCP usage
• Agent binding support for linking characters to named agents in your MCP client config (OpenClaw agent ID validation built-in)
• Guided character intake with draft creation, resumable next-step guidance, intake status, batch answer application, optional place/object creation, completion summaries, empty-dataset detection, guided import of already-known characters, and a dedicated proposed-identity facet for tentative framing
• Visual consistency metadata for canonical image refs, preferred image models, seeds, prompt notes, and LoRA/training-prep refs
• Entity summaries include a related_entities manifest so the AI sees all linked entities without a separate call
• Non-character entity responses (get_entity_summary, get_entity_facet) include a character_essentials block from the owning character — prevents identity drift during image generation
• Doctor checks for misplaced entity-type data: location prose in character facets, object details in character prose, and place/object entities with no character referencing them
• Optional debug logging to ~/.character-mcp/debug.log (ndjson, rotating) for auditing which tools the AI calls
• Safe local sample dataset for development and testing

Installation

From PyPI

https://pypi.org/project/character-mcp/

pip install character-mcp

Install into a dedicated venv to keep it isolated from other tools:

python3 -m venv ~/character-mcp-venv
~/character-mcp-venv/bin/pip install character-mcp

From the GitLab Package Registry

If you need a pre-release build or a specific commit's artifact:

pip install character-mcp \
  --index-url https://gitlab.com/api/v4/projects/DigitalGert%2Fcharacter-mcp/packages/pypi/simple

From source

git clone https://gitlab.com/DigitalGert/character-mcp.git
cd character-mcp
pip install -e .

Client Configuration

Set CHARACTER_MCP_ROOT to the directory containing your characters/, places/, and objects/ folders.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "character-mcp": {
      "command": "character-mcp-server",
      "env": {
        "CHARACTER_MCP_ROOT": "/path/to/your/characters"
      }
    }
  }
}

If installed into a venv, use the full path to the binary:

"command": "/home/you/character-mcp-venv/bin/character-mcp-server"

OpenClaw

In ~/.openclaw/openclaw.json under mcp.servers:

{
  "mcp": {
    "servers": {
      "character-mcp": {
        "command": "/home/you/character-mcp-venv/bin/character-mcp-server",
        "args": [],
        "env": {
          "CHARACTER_MCP_ROOT": "/path/to/your/characters",
          "CHARACTER_MCP_TRANSPORT": "stdio"
        }
      }
    }
  }
}

Generic MCP client

Any client that supports stdio MCP servers needs:

• Command: character-mcp-server (or full venv path)
• Environment: CHARACTER_MCP_ROOT=/path/to/your/characters

See the Configuration section for all available environment variables.

MCP Tool Surface

Read tools

• get_dataset_status
• list_entities
• get_entity_summary
• list_entity_facets
• get_entity_facet
• list_entity_relationships
• get_related_entities
• get_visual_profile
• doctor_entity_index
• cleanup_dataset
• rescan_entities
• get_character_intake_status
• get_character_intake_next_step
• suggest_next_character_questions
• get_character_gap_report
• get_character_agent_binding

Write tools

• load_example_dataset
• initialize_character_root
• create_entity
• start_character_intake
• start_existing_character_import
• apply_character_intake_answers
• link_character_agent
• update_entity_yaml
• write_entity_facet
• add_relationship
• append_entity_alias
• add_asset_reference
• localize_asset_reference
• update_visual_profile

These are intentionally narrow. The server does not support delete operations, arbitrary file mutation, or binary asset writes.

Facet Granularity

Character facets should be narrow and retrievable. Prefer one file per question the agent might reasonably ask.

Prefer:

• outfit-team-hoodie
• outfit-bjj
• ritual-morning-espresso
• ritual-evening-decompression

Avoid broad buckets like:

• wardrobe
• rituals
• rituals-and-wardrobe

If one file starts bundling multiple distinct outfits, rituals, or modes, split it. That keeps MCP retrieval targeted and reduces accidental overfetching.

For character entities, known broad bucket facets like wardrobe and rituals are now rejected at write time rather than accepted and warned about later.

Configuration

All configuration is via environment variables set in your MCP client config (e.g. claude_desktop_config.json):

Variable	Default	Purpose
CHARACTER_MCP_ROOT	(required)	Path to your character dataset
CHARACTER_MCP_TRANSPORT	stdio	Transport: stdio or sse
CHARACTER_MCP_WATCH	0	Set to 1 to auto-reload on file changes
CHARACTER_MCP_WATCH_INTERVAL	1.0	Seconds between watch polls
CHARACTER_MCP_OPENCLAW_CONFIG	(none)	Path to openclaw.json for agent ID validation (OpenClaw-specific, optional)
CHARACTER_MCP_DEBUG_LOG	0	Set to 1 to enable debug logging
CHARACTER_MCP_LOG_LEVEL	info	Log detail level: info or debug

When CHARACTER_MCP_DEBUG_LOG=1, every tool call is appended as a JSON object to ~/.character-mcp/debug.log (ndjson format, rotating at 5MB, 2 backups). At info level each entry includes timestamp, tool name, arguments, duration, and a result size hint. At debug level the full result is also included.

Example:

{"ts": "2026-04-19T17:00:00Z", "tool": "get_entity_summary", "args": {"entity_id": "dara"}, "duration_ms": 4.2, "result_hint": {"type": "dict", "related_entities_count": 3}}

Empty Dataset and Existing-Character Flow

Character MCP can now detect an empty character root and help the host start cleanly.

Current behavior:

• get_dataset_status reports whether the configured root exists, whether it is initialized, whether it is effectively empty, and what the next comfortable setup actions are
• initialize_character_root creates the basic characters/, places/, and objects/ folders plus a starter README.md
• start_existing_character_import creates a draft character tagged for import and frames the rest of the work as gradual confirmation of recalled knowledge rather than blind freeform writes
• new linked place and object entities now require a real summary plus non-placeholder profile.md content; stub shells are rejected instead of silently accepted

This is the basis for a welcome flow where an empty install can offer:

• initialize the dataset
• start a new character
• add someone the model already knows from context, with explicit confirmation before storing that knowledge

Local Development

To run the server against the bundled sample dataset during development:

uv run character-mcp-server
# or
python -m character_mcp.server

Set CHARACTER_MCP_ROOT to point at any character dataset directory. The build/sample-data/characters_root directory in this repo is a safe scratch dataset for testing.

Roadmap

The living roadmap is in ROADMAP.md.

The active product direction:

1. guided character intake expansion
2. deeper visual/reference workflows on top of the new visual profile support
3. gap detection and next-step guidance
4. packaging and install flow

Current Rough Edges

• import and intake quality can still drift semantically even when the writes are structurally valid
• linked entities can still be too thin if the model does not have enough grounded detail

Build and Release Model

GitLab CI runs on every push: tests, builds the wheel, and smoke-tests the install. On version tags (v0.3.x), it also publishes to the GitLab Package Registry and creates a release entry.

Artifacts from non-tagged builds are kept for 30 days and accessible from the pipeline's build job if you need a specific commit's build.

Non-Goals

This project is not, for now:

• a semantic search engine
• a digital asset manager
• a hosted multi-user database
• a repo for personal production character data