Amsel MCP Server

Version française

An MCP server that gives Claude (or any MCP client) read access — and, if you enable it, write access — to Amsel Suite files: Tome campaigns (.tome), Lore worlds (.lore) and Lore template kits (.lorekit).

Claude can browse your campaign tree, read an NPC or a Lore page, follow links between pages, check arcanes and their per-session results, and search all your content. With writing enabled, it can also create NPCs, scenes and Lore pages, extend existing text, add session notes and set images.

Community project, not affiliated with or endorsed by Ollam Technologies, the makers of Amsel Suite. The file format was reverse-engineered and may change with new Amsel versions: work on copies first.

Read tools (always available)

Related MCP server: OpenFic MCP

Write tools (with AMSEL_WRITE=1)

Text is written in light Markdown: one paragraph per line, **bold**, *italic*, ### / #### headings, --- separators, - or 1. lists (indent by 2 spaces for a sub-list), > quotes, and [[Page name]] links to existing pages (Tome or linked Lore). A missing or ambiguous link cancels the write.

Safeguards — without AMSEL_WRITE=1, the write tools do not exist. When they are enabled, every write:

• is refused while the Tome app (for a .tome) or the Lore app (for a .lore) is open, since the app would overwrite the change on its next save;

• is refused if the file changed on disk while the edit was being prepared;

• first copies the file to .amsel-backups/ next to it (the last 20 versions are kept);

• rewrites the archive into a temporary file, reads it back to check it, then replaces the original. Existing images are left untouched; new ones are added to img/ and to the image library (in the folder you choose).

There is no deletion yet, and arcanes, relations and runes cannot be edited. Images come from local files: an online image must be downloaded first.

Files and pages are referenced by name, partial name or id (or the start of an id). Amsel links appear as [[Page name]].

The amsel-adventure-writer skill

skills/amsel-adventure-writer is a Claude skill that uses this server to write playable adventures: structured scenes (setting, read-aloud text, checks and consequences, exits), NPCs and locations you can improvise with, and Lore pages built on your templates (drawing on .lorekit kits). It first reads the campaign (tree, session notes, arcanes, the GM's style), proposes a plan, then writes in the right order so that links resolve. It writes in the language of your campaign.

Install it for Claude Code:

ln -s "$PWD/skills/amsel-adventure-writer" ~/.claude/skills/amsel-adventure-writer

Installation

📘 Step-by-step guide, from nothing to the first question, with troubleshooting: docs/installation.md

Requirements: uv (it installs Python 3.10+ for you).

git clone https://github.com/Dimitri-byte/Amsel-MCP-Server.git
cd Amsel-MCP-Server
uv sync

Scanned folders

AMSEL_PATHS tells the server where to look for files (several folders separated by : on Linux/macOS, ; on Windows). Subfolders are scanned, hidden folders are skipped. Default: ~/Documents.

Claude Code

claude mcp add --scope user amsel -e AMSEL_PATHS="$HOME/Documents" -- uv run --directory /path/to/Amsel-MCP-Server amsel-mcp

Add -e AMSEL_WRITE=1 to enable the write tools.

Claude Desktop

In claude_desktop_config.json:

{
  "mcpServers": {
    "amsel": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/Amsel-MCP-Server", "amsel-mcp"],
      "env": { "AMSEL_PATHS": "/home/me/Documents" }
    }
  }
}

Amsel file format (reverse-engineered)

• A .tome or .lore is a tar archive (pax format) holding data.json (minified JSON) and an img/ folder (<uuid>.<ext>, plus optional <uuid>.thumb.400.png thumbnails). Images are listed in importedImages and sorted into imageFolders.

• When a file is opened, the app unpacks it into ~/.amselsuite/<uuid>/; those are working copies, the server always reads the archives.

• Tome (lastVer 24): storyPages (types TSP_Story, TSP_ChapterFlow, TSP_Chapter, TSP_Scene, tree via parentId / childrenIds), dataPages (TDP_Character, TDP_Location, TDP_Object, TDP_Organization, TDP_Player, TDP_Fable, with text or checker sub-pages), arcanes (choice / destiny), gameSessions, notes, linkedLorePath. Page covers: coverImage.relatedImage.

• Lore (lastVer 17): pages (content per module via relatedModuleId; images via visualContent.relatedImage), templates (modules LM_Standard_Text, LM_Image, LM_Rune, LM_Mirror), runeTemplates, diagrams, maps.

• Lore kit (.lorekit): the same archive with no pages or images, only name, templates and runes. Old format (lastVer 13): runeTemplates[].runelets. Newer format (lastVer 23): runeGroups[].runes, customTemplateCategories (custom categories referenced by id) and inspirationLists. The server reads both but never writes to a kit: kits are imported into a Lore from the app.

• Rich text is HTML. Links: <tag-component id="lorePage/…"> (Lore page), index/… (Tome data page), storyPage/…; embedded arcanes: <destiny-component idhash="…">, <intrigue-component …>.

• Linked Lore: the server first looks for a .lore with the same name next to the Tome (handy for copies), then for the recorded path.

Development

uv run pytest

The tests use synthetic files generated on the fly. If AMSEL_TEST_DIR points to a folder of real Amsel files, extra tests check that every page renders. Never commit real .tome / .lore / .lorekit files (they are in .gitignore).

Contributions are welcome: see CONTRIBUTING.md. Changes are listed in CHANGELOG.md.

Roadmap

• Reading Tome, Lore and Lore kits

• Writing: page creation and editing, session notes, images (backups, refused while the app is open)

• Arcanes (per-session results), relations, runes

• Page deletion

License

MIT. Amsel Suite, Tome and Lore are trademarks of their respective owners.