English | 中文
Structure your marketing data so AI can find it, understand it, and put it to work.
The way most marketing tools store data — fragments of text in 10 different SaaS products, raw files in cloud drives, brand rules buried in PDFs — makes them invisible to AI. OpenLucid is a self-hosted layer that pulls all of it together, structures it, and exposes it through three first-class interfaces: MCP for AI agents, REST API for automation, and a Web UI for marketing teams.
The same brand knowledge that powers your Web UI directly powers Claude Code, Cursor, OpenClaw, and any custom agent — without copy-paste.
⭐ If OpenLucid helps you, please give us a star — it really helps the project grow.
- 🧠 AI-readable by design — Knowledge, audiences, scenarios, brand rules, assets — every field is structured, scored, and tagged. Not raw files and free text.
- 🔌 MCP-first — External agents are the brain. OpenLucid contributes the prompt discipline + the data layer; Claude / GPT / your-own-LLM stays in charge of reasoning.
- 🛡️ Server-enforced rules — Things like merchant defaulting and source-of-truth conflicts are guarded server-side, not by hoping the agent reads instructions.
- ⚙️ Self-hosted, single-tenant — Your data, your DB, your model keys. Two containers, no Redis, no message queue.
- 🌐 Three interfaces, one source of truth — Web UI, REST API, MCP, and a CLI. Add an offer in any of them — the others see it instantly.
| Module | What it does |
|---|---|
| 🧠 Knowledge Base | Structured merchant knowledge: selling points, audience insights, usage scenarios, FAQs, objection handling. Manual or AI-inferred. |
| 📁 Asset Library | Upload images, videos, documents. AI auto-extracts metadata, tags, scores. Filter by content-form (unboxing/review/tutorial) or campaign-type (flash sale/BOGO). |
| 🎯 Strategy Units | Define audience × scenario × goal × channel combos to focus content direction. |
| 🎨 Brand Kit | Logo, brand voice, colors, fonts, persona presets — guardrails that keep all output on-brand. |
| 💡 Topic Studio | Generate multi-platform topic plans grounded in your KB and assets. |
| ✍️ Script Writer / Content Studio | Produce short-video scripts or social copy with platform × persona × structure presets. |
| 🎬 Video Generation | Turn a script into a digital-human video via Chanjing / Jogg (avatar + voice + aspect + B-roll + captions). |
| 📚 Creations Library | Every finished piece (post / script / email / hook) auto-saved for reuse, comparison, and agent referral. |
| ❓ KB Q&A | AI-powered Q&A that cites your knowledge base without fabricating. |
Three interfaces, pick what fits — they all read and write the same data:
| Interface | For | How |
|---|---|---|
| MCP Server | Claude Code, Cursor, OpenClaw, AI IDEs | Connect via MCP protocol; AI reads your marketing data directly |
| RESTful API | Custom agents, automation | Full API with interactive docs at /docs |
| CLI Tool | Agent scripting, ops queries | Standalone Python script over HTTP, zero project deps |
| Web UI | Marketing teams | Visual UI for managing knowledge, assets, brand kits, topics |
Prerequisites: Docker and Docker Compose installed and running.
git clone https://github.com/agidesigner/OpenLucid.git
cd OpenLucid/docker
cp .env.example .env
docker compose up -dOnce started, open http://localhost :
- First visit lands on the setup page — create your admin account
- Go to Settings to configure your LLM (any OpenAI-compatible API)
- Create your first product / offer and start planning
- (Optional) Install the CLI so AI agents can query your marketing data:
bash tools/install.sh openlucid setup
💡 Only 2 containers (PostgreSQL + App). No Redis, no message queue, no extra dependencies.
OpenLucid is built MCP-first. After running bash tools/install.sh, the OpenLucid skill is registered globally so any agent in any project directory discovers it automatically:
| Agent | Skill installed at |
|---|---|
| Claude Code | ~/.claude/skills/openlucid/SKILL.md |
| Cursor | ~/.cursor/skills/openlucid/SKILL.md |
| Codex / OpenHands | ~/.agents/skills/openlucid/SKILL.md |
Now ask your agent things like:
- "List all merchants and offers for my workspace"
- "Import this product URL into OpenLucid and infer the knowledge base"
- "What are the key selling points of [product]?"
- "Draft a Xiaohongshu post for [product] using its brand voice"
The agent uses the OpenLucid MCP to read structured data, calls the LLM to reason, and writes the result back via add_knowledge_item / save_creation — all under your data sovereignty.
Run from the docker/ directory:
docker compose up -d # Start
docker compose down # Stop
docker compose restart # Restart
docker compose logs -f app # View logs
docker compose ps # Check statusAll settings are managed in docker/.env (template at docker/.env.example):
| Variable | Default | Description |
|---|---|---|
DB_USER |
openlucid | Database username |
DB_PASSWORD |
openlucid | Database password (change in production!) |
DB_NAME |
openlucid | Database name |
APP_PORT |
80 | Port exposed on host |
SECRET_KEY |
change-me-in-production | JWT secret (change in production!) |
LOG_LEVEL |
INFO | Log level |
LLM configuration lives in the Web UI (Settings → LLM) — supports multiple models, scene-based routing, visual switching.
Q: Why "Marketing World Model"? A new marketing app needs structured ground-truth about products, brand voice, audiences, and assets to reason well. OpenLucid is that ground-truth layer — designed to be queried and updated by AI agents, not just humans.
Q: Do I need a specific LLM? No. OpenLucid speaks the OpenAI Chat Completions API; any compatible LLM works (Claude, GPT, DeepSeek, Qwen, Gemini, Ollama, your own). You configure model + key in the Web UI.
Q: Does it talk to MCP clients other than Claude Code?
Yes. Anything that speaks MCP (Cursor, OpenClaw, custom clients) connects via the same /mcp endpoint. Tool list, prompts, and resources are identical across clients.
Q: How is data stored?
PostgreSQL 16 in your own container. No SaaS, no third-party vector DB, no telemetry. Asset files live on the host disk under uploads/.
Q: Can I run it offline / behind a VPN? Yes — once dependencies are installed, the only outbound traffic is to your configured LLM endpoint (and optional video provider Chanjing/Jogg if you use Video Generation).
Q: I forgot my admin password / lost access to my email / need to provision the first admin from a script.
See the Self-Hosting Operations Guide — there's a direct-DB CLI (docker compose exec app python -m app.cli ...) that bypasses email and HTTP entirely for these recovery cases.
Q: Can I customize the writing rules per platform (WeChat / blog / xiaohongshu / ...) or per persona / narrative-structure?
Yes — every platform / persona / narrative-structure / content-form / campaign-type prompt ships as a markdown file you can edit. The shipped defaults stay in git, your customizations live in a docker volume that survives git pull. See SELF_HOSTING.md#customizing-content-generation-prompts.
| Layer | Technology |
|---|---|
| Backend | Python 3.11 · FastAPI · SQLAlchemy 2.0 (async) · Alembic |
| Database | PostgreSQL 16 |
| Frontend | HTML · Tailwind CSS · Alpine.js (no build step) |
| AI | OpenAI SDK (compatible with any OpenAI-format LLM API) |
| Deployment | Docker Compose |
Find me on 𝕏 / Twitter — I share notes on building OpenLucid, marketing AI patterns, and self-hosted agent setups:
Or reach out at ajin@jogg.ai for partnership / commercial inquiries.
- 🐛 Found a bug → open an Issue
- 💡 Feature idea → open a discussion or feature request
- ⭐ Liked it? → Star this repo so more people find it!
OpenLucid is available under a modified Apache License 2.0 with additional conditions for multi-tenant use and branding. See LICENSE for details.