Loreum MCP Server

<p align="center"> <img src="apps/web/public/loreum-logomark.png" alt="Loreum" width="80" /> </p>

<h1 align="center">Loreum</h1>

<p align="center"> Every character, faction, and timeline in one searchable place.<br/> The worldbuilding platform that makes AI useful. </p>

<p align="center"> <a href="https://loreum.app">Website</a> · <a href="https://discord.gg/A2s5gZ8rcz">Discord</a> · <a href="https://loreum.app/roadmap">Roadmap</a> · <a href="https://loreum.app/docs">Docs</a> </p>

<p align="center"> <a href="https://github.com/loreum-app/loreum/actions"><img src="https://github.com/loreum-app/loreum/actions/workflows/ci.yml/badge.svg" alt="CI" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue" alt="License" /></a> <a href="https://discord.gg/A2s5gZ8rcz"><img src="https://img.shields.io/discord/1492392236867125422?color=5865F2&label=discord" alt="Discord" /></a> </p>

---

Loreum is a database for fictional worlds. Track characters, relationships, timelines, organizations, maps, lore, and story structure in a purpose-built platform with instant search across everything. No scattered files, no lost notes, no contradictions.

AI plugs into all of it. Connect Claude, Cursor, or any MCP-compatible assistant, and it reads your entire world: entities, relationships, timeline, lore, style guide, and storyboard. It can also propose changes that land in a review queue for you to accept, edit, or reject before anything touches your canon.

For novelists, screenwriters, game designers, tabletop RPG game masters, comic book writers, and anyone building a fictional universe that needs structure.

Features

• Entities - Characters, locations, organizations, and custom types with configurable field schemas, backstories, and secrets
• Knowledge Graph - Visual relationship editor showing how everything in your world connects (React Flow)
• Timeline - Events and eras on an interactive Gantt chart with drag-to-edit and custom calendar support
• Lore Wiki - Canonical world articles with entity mentions, categories, and tags
• Storyboard - Plotlines, works, chapters, and scenes cross-referenced to your world data
• Style Guide - Voice, tone, POV, pacing, dialogue rules, scene overrides, and per-character voice notes
• AI Integration (MCP) - 11 read tools and 16 write tools so any MCP-compatible AI can query and modify your world
• Review Queue - AI-proposed changes land in a staging area with diff view. Accept, edit, or reject individually or in batch
• API Key Auth - Project-scoped keys with read-only or read-write permissions for MCP authentication
• Public Wiki - Share your world as a read-only site while keeping secrets and drafts private
• Maps - Upload map images and pin locations with coordinates
• Search - Full-text search across all content

How It Works

1. Build your world in the Loreum web app with entities, relationships, timelines, lore, and a style guide
2. Add AI by bringing your own via MCP or using the built-in assistant. Build solo or invite collaborators
3. Write with context as AI reads your canon to generate grounded content. Proposed changes go through a review queue

Tech Stack

Layer	Technology
Frontend	Next.js 16, React 19, shadcn/ui, Tailwind
API	NestJS, Prisma 7, PostgreSQL 18
Queue	BullMQ + Redis 7
Auth	OAuth2 (Google) + JWT with token rotation
Graph	React Flow (@xyflow/react)
AI	MCP protocol (Model Context Protocol)
Storage	Cloudflare R2 (S3-compatible)
Infra	Cloudflare CDN + Tunnel
Testing	Vitest, Supertest, GitHub Actions CI
Monorepo	Turborepo + pnpm

Quick Start

# Clone the repo
git clone https://github.com/loreum-app/loreum.git
cd loreum

# Install dependencies
pnpm install

# Copy environment files
cp .env.example .env
cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env

# Start Postgres + Redis
docker compose up -d

# Generate Prisma client, run migrations, and seed demo data
pnpm --filter api db:generate
pnpm --filter api db:migrate
pnpm --filter api db:seed

# Start development (all apps)
pnpm dev

API: http://localhost:3021 | Web: http://localhost:3020 | Swagger: http://localhost:3021/docs

MCP Server

Connect any MCP-compatible AI to read and write your world data. Generate a project-scoped API key from project settings, then configure your client:

{
  "mcpServers": {
    "loreum": {
      "command": "node",
      "args": ["path/to/loreum/apps/mcp/dist/index.js"],
      "env": {
        "MCP_API_BASE_URL": "https://api.loreum.app/v1",
        "MCP_API_TOKEN": "your-api-key"
      }
    }
  }
}

All write operations go through the review queue. Full MCP documentation.

Project Structure

apps/
  api/          NestJS API (Prisma, BullMQ, WebSocket)
  web/          Next.js frontend (shadcn/ui, React Flow)
  mcp/          MCP server for AI tool integration
packages/
  types/        Shared TypeScript interfaces
  ui/           Shared UI components
  typescript-config/
  eslint-config/
docs/
  PRODUCT_SPEC.md         Full feature specification
  SYSTEM_ARCHITECTURE.md  Architecture diagrams
  API_REFERENCE.md        REST, WebSocket, MCP docs
  USER_JOURNEYS.md        User flow documentation
  ERD.md                  Entity-relationship diagram
  DEPLOYMENT.md           Production deployment guide
  TODO.md                 MVP checklist and roadmap

Documentation

Document	Description
Product Spec	Complete feature specification with tiers
System Architecture	Component, data flow, and deployment diagrams
API Reference	REST, WebSocket, and MCP tool documentation
User Journeys	User flow documentation
ERD	Entity-relationship diagram
Deployment	Production deployment guide
TODO	MVP checklist and roadmap
Changelog	Version history

Community

• Discord - Questions, feedback, and discussion
• Contributing - Development setup, code conventions, PR process
• Code of Conduct - Community standards
• Security - How to report vulnerabilities

License

AGPL-3.0