Content
# Obsidian D&D MCP
> Status: experimental. The current focus is a clear vault structure, a working MCP access layer, and reusable examples.
## Overview
Obsidian D&D MCP is a framework for persistent campaign memory in AI-assisted tabletop RPG campaigns.
It uses an Obsidian vault as the long-term memory layer and an MCP server as the structured access layer. The goal is to help an AI assistant consult, update, and preserve campaign context across long-running sessions.
The repository includes a public `example-vault` that shows the intended structure. It is not a complete campaign.
## Who Is This For?
This project is intended for:
- AI-assisted tabletop RPG campaigns
- Dungeon Masters using Obsidian
- Players who want persistent campaign memory
- Long-running campaigns where continuity matters
It is especially useful when chat history alone is no longer sufficient to maintain campaign consistency.
## Quick Start
At a high level:
1. Clone the repository.
2. Install the MCP server dependencies.
3. Copy or adapt the example vault.
4. Configure the server to point to your local Obsidian vault.
5. Start the MCP server.
6. Connect it to your preferred MCP-compatible AI client.
7. Verify that the vault tools are available.
8. Ask the assistant to inspect the vault index before starting or resuming a campaign.
Clone the repository and install the server dependencies:
```bash
git clone https://github.com/Svarion317/obsidian-dnd-mcp.git
cd obsidian-dnd-mcp/server
npm install
```
Create a working vault from the example structure:
```bash
cp -R ../examples/example-vault ../my-campaign-vault
```
Configure the server environment:
```bash
cp .env.example .env
```
Then edit `.env` and set the vault path to your local vault folder.
Start the MCP server:
```bash
npm start
```
The exact client connection process depends on the AI client being used. Refer to your client's MCP documentation and to `server/README.md` for setup details.
## The Problem
Long-running AI-assisted campaigns can lose continuity over time.
Common failure points include:
- forgotten character details
- outdated inventory
- inconsistent NPC behavior
- disconnected worldbuilding
- unresolved plot threads
- campaign history buried in chat logs
- combat state handled only from memory
Chat history alone is not a reliable campaign database.
## The Solution
This project separates campaign memory from chat history.
It combines:
- Obsidian for persistent notes
- MCP for structured vault access
- modular campaign files
- DM operating instructions
- campaign state updates
- combat preparation notes
The AI can inspect the relevant files before responding instead of relying only on the current conversation.
## High-Level Workflow
```text
Obsidian Vault
|
v
MCP Server
|
v
AI Assistant
|
v
Reads relevant context
|
v
Runs or supports the campaign
|
v
Prepares vault updates
|
v
Obsidian Vault
```
## Memory Pipeline
The vault is organized as a memory pipeline. Each layer has a specific role, so the AI can load only the context needed for the current scene.
### Character Layer
Character files are the source of truth for the player character.
They can include:
- character sheet
- inventory
- background
- goals
- personal history
### Campaign State Layer
Campaign state tracks what is currently true in the campaign.
It can include:
- current location
- active objectives
- recent events
- open questions
- important consequences
- session records
Historical notes should stay separate from active state so current information does not get buried.
### Worldbuilding Layer
Worldbuilding files store reusable setting information.
They can include:
- locations
- factions
- organizations
- cosmology
- mysteries
- secrets
- historical events
### NPC Layer
NPC files keep recurring characters consistent.
They can include:
- identity
- role
- motivations
- relationships
- known information
- secrets
- current status
### DM Instruction Layer
DM instruction files define how the AI should run and maintain the campaign.
They can include:
- narrative guidelines
- continuity rules
- consultation rules
- update procedures
- campaign management procedures
### Combat Layer
Combat has its own workflow because combat state is easy to lose in chat.
The example vault includes files for:
- encounter design
- combat balancing
- active encounter tracking
## Repository Structure
```text
examples/
└── example-vault/
├── 00_Campagna/
├── 01_Personaggio/
├── 02_Istruzioni_DM/
├── 03_Combattimento/
├── 04_Manuali/
└── 05_Template/
server/
README.md
```
- `examples/example-vault/`: public demo vault that shows the recommended structure.
- `examples/example-vault/00_Campagna/`: campaign state, saves, NPCs, and worldbuilding.
- `examples/example-vault/01_Personaggio/`: example character sheet, inventory, and background files.
- `examples/example-vault/02_Istruzioni_DM/`: operational instructions for the AI Dungeon Master.
- `examples/example-vault/03_Combattimento/`: combat preparation and active encounter files.
- `examples/example-vault/04_Manuali/`: placeholder for manuals. No D&D manuals are included.
- `examples/example-vault/05_Template/`: reusable templates for campaign notes.
- `server/`: MCP server that exposes structured vault tools.
- `README.md`: project overview.
## Example Vault
The public example vault is located at:
```text
examples/example-vault/
```
It is a demonstration vault. It shows how to organize campaign memory, templates, DM instructions, and combat notes.
It does not include:
- a private campaign vault
- a complete playable campaign
- official D&D rulebooks
- copyrighted manual content
The `04_Manuali` directory exists only as a placeholder. Add only material you are allowed to use in your own private vault.
## Typical Workflow
### Preparing the Campaign
Before starting, prepare the minimum memory needed for the AI to stay consistent:
- character sheet
- character inventory
- character background
- starting campaign state
- core worldbuilding notes
- DM instructions for tone and operating rules
Discuss the campaign world with the AI before the first session, then record the agreed information in the vault.
Useful topics include:
- tone and genre
- starting location
- major factions
- important conflicts
- known mysteries
- secrets the character does not know
- what the character already knows
### Starting a Campaign
1. Copy or adapt the example vault structure.
2. Fill in the prepared character, campaign state, and worldbuilding files.
3. Connect the MCP server to the vault.
4. Ask the AI to consult the relevant files before play begins.
### Resuming a Session
At the start of a session, the AI should inspect the current state and any relevant character, NPC, worldbuilding, or combat files.
The goal is to resume from recorded campaign memory, not from vague chat recall.
### Updating the Campaign
After important events, update the vault.
Typical updates include:
- current state changes
- new NPC information
- inventory changes
- completed objectives
- new unresolved threads
- consequences of player actions
- session records or campaign saves
## Combat Workflow
Combat notes should be prepared before initiative when possible.
The example vault separates:
- encounter design
- balancing notes
- active encounter state
This project does not implement D&D rules. It provides a place to store and retrieve the combat context the AI needs to run a scene consistently.
## MCP Server
The `server/` directory contains an MCP server for working with an Obsidian vault.
It exposes the following vault tools:
- `list_vault_files`
- `read_vault_file`
- `search_vault`
- `write_vault_file`
- `append_vault_file`
- `replace_in_vault_file`
- `read_vault_headings`
- `find_vault_backlinks`
- `rename_vault_file`
- `suggest_context_files`
- `suggest_save_update`
The first group provides basic vault access and Markdown file operations. The pipeline tools help the assistant identify relevant context and prepare campaign save updates.
See `server/README.md` for the existing server setup notes.
## What This Project Is Not
This project is not:
- a complete D&D campaign
- a VTT
- a rules engine
- a character builder
- a replacement for the Dungeon Master
- a source of official D&D rules or manuals
It is a memory framework and template for AI-assisted campaign continuity.
## Manuals and Reference Files
This repository does not include official D&D manuals, copyrighted rulebooks, or proprietary content.
Users may add their own local reference files inside their private vault. For the example structure, use `examples/example-vault/04_Manuali/`; in your own vault, use `04_Manuali/`.
Reference files can include personal notes, summaries, house rules, SRD-compatible material, or private reference documents you are allowed to use.
The AI should consult manuals and reference files only when a rule, spell, item, class feature, condition, combat procedure, or mechanical uncertainty is relevant.
The example vault should show only the structure and placeholders, not actual copyrighted manual text.
## License
This project is released under the MIT License.
See the LICENSE file for details.
