LoreKeeper

Semantic search tools for D&D5e w/ Open5e and .orcbrew import

python

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "frap129-lorekeeper-mcp": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "-m",
        "lorekeeper_mcp"
      ],
      "env": {
        "LOREKEEPER_DEBUG": "false",
        "LOREKEEPER_DB_PATH": "./data/cache.db",
        "LOREKEEPER_LOG_LEVEL": "INFO",
        "LOREKEEPER_CACHE_BACKEND": "milvus",
        "LOREKEEPER_CACHE_TTL_DAYS": "7",
        "LOREKEEPER_MILVUS_DB_PATH": "~/.local/share/lorekeeper/milvus.db",
        "LOREKEEPER_EMBEDDING_MODEL": "all-MiniLM-L6-v2",
        "LOREKEEPER_OPEN5E_BASE_URL": "https://api.open5e.com",
        "LOREKEEPER_ERROR_CACHE_TTL_SECONDS": "300"
      }
    }
  }
}

LoreKeeper MCP is a Python-based MCP server that provides fast, cached access to D&D 5e data for AI assistants. It integrates data from Open5e, supports semantic search via Milvus Lite, and exposes a production-ready server you can query through MCP clients.

How to use

Start the server using the built CLI. Run the server directly with the standard command lorekeeper serve to begin listening for MCP requests. You can enable verbose output with lorekeeper -v serve or customize the cache path with lorekeeper --db-path /custom/path.db serve. For a backward-compatible workflow, launch the server through the runtime wrapper: uv run python -m lorekeeper_mcp. Once running, connect your MCP client to the local server using the default MCP transport and issue lookup, search, and import requests as you would with other MCP services.

How to install

Prerequisites: Python 3.11 or higher and the uv tool for package management.

# Clone the LoreKeeper MCP repository
git clone https://github.com/your-org/lorekeeper-mcp.git
cd lorekeeper-mcp

# Install dependencies
uv sync

# Set up pre-commit hooks
uv run pre-commit install

# Copy environment configuration
cp .env.example .env

Additional notes

Start options shown here are intended to be run directly from your shell or via the uv wrapper. The server exposes MCP endpoints you interact with from your client. You can tailor the runtime with a custom database path by providing the --db-path argument. Ensure your environment is prepared with the required variables in a .env file if you plan to customize backend or logging behavior.

Environment and configuration

Configure the application through environment variables with the LOREKEEPER_ prefix. Common settings include the cache backend, embedding model, and the Open5e API base URL.

Troubleshooting tips

If the server fails to start, verify you have Python 3.11+ installed and that uv is available for running commands. Check that no other process is occupying the default MCP port and that the environment file is present (.env) with the required variables.

Available tools

search_spell

Query spells by name, level, school, class, and properties using the semantic search and exact filters.

search_creature

Query monsters by name, CR, type, and size with optional semantic filtering.

search_character_option

Retrieve classes, races, backgrounds, and feats.

search_equipment

Query weapons, armor, and magic items.

search_rule

Lookup game rules, conditions, and reference information.

search_all

Unified search across all content types with semantic capabilities.

Built by

VeilStrat

AI signals for GTM teams