io.github.Kumar2421/marlo-mcp

Open-source AI CMO. Marlo audits your website, finds what's holding it back in search and AI answers, helps you fix it, and only calls a fix verified when it has evidence.

Hosted app · Self-host · Docs · Pricing (beta) · Changelog

Marlo is one Next.js app. Use the hosted version, or self-host it for free with your own API keys. Self-host has every feature unlocked and no plan limits.

Marlo is inspired by Okara. It is an independent project: not affiliated with or endorsed by Okara, and not derived from Okara's code.

What Marlo does

Marlo runs one loop: discover → understand → act → verify. "Verified" always means evidence: a later audit, a re-check, or a real AI-answer run. A click alone never verifies anything.

More screenshots

Status

Marlo is in beta. This table says what to rely on today.

Hosted or self-host

You can also run the hosted build on your own Supabase project. See docs/self-hosting.md.

Quick start

Self-host

Requires Node.js 24.12 or newer (engines in package.json) and git.

git clone https://github.com/Kumar2421/okara-alternative.git
cd okara-alternative
npm install
echo "NEXT_PUBLIC_SELF_HOST=true" > .env.local
npm run dev

1. Open **http://localhost:3000/dashboard**. The root URL redirects to the hosted sign-in page, which needs Supabase.
2. To check the setup, open http://localhost:3000/api/system/storage-diagnostics. You should see "storageMode":"sqlite" and "available":true under sqlite.
3. In Settings → LLM Providers, add at least one model key. The providers with drivers are Anthropic, OpenAI, Google, Mistral and Groq, plus a local Ollama or LM Studio server or any other OpenAI-compatible endpoint. Add optional keys under Settings → API Credentials: Tavily for web search, PageSpeed, Gemini for real GEO answers, Google Cloud, and a GitHub token for fix PRs.
4. Add your website. Setup runs while the tab is open.

No environment variables are required in self-host mode. Optional ones, such as Gmail OAuth or Resend email, are listed in docs/environment.md. For a production-style build, run npm run build and then npm start. For full steps and troubleshooting, see docs/self-hosting.md.

Docker

No Node or npm needed:

git clone https://github.com/Kumar2421/okara-alternative.git
cd okara-alternative
docker compose up -d --build

Or skip the build: docker run -d -p 127.0.0.1:3000:3000 -v marlo-data:/app/data ghcr.io/kumar2421/marlo:latest.

Open http://localhost:3000/dashboard** and add a model key in **Settings → LLM Providers. Your data lives in the marlo-data volume. The port is bound to your machine only; to share it, set MARLO_ACCESS_PASSWORD, put HTTPS in front and change the port mapping. Details: docs/self-hosting.md.

Use Marlo from your AI assistant (MCP)

marlo-mcp lets Claude, Cursor, Windsurf and other MCP clients audit a page from chat. Add it to your client:

{ "mcpServers": { "marlo": { "command": "npx", "args": ["-y", "marlo-mcp"] } } }

Claude Code: claude mcp add marlo -- npx -y marlo-mcp. Then ask: "Audit https://mysite.com and tell me what to fix first."

It is read-only and audits one page. Point it at your own server with MARLO_BASE_URL (and MARLO_ACCESS_PASSWORD if you set one). See packages/marlo-mcp/README.md.

Hosted

Sign up at **https://app.marlo.mlforge.in**. To run your own hosted deployment (Supabase and Vercel), follow docs/hosted-setup.md and docs/self-hosting.md.

How it works

flowchart LR
  U["Browser: dashboard"] -->|setup steps, Re-check| API["Next.js route handlers"]
  API --> D["lib/domain: audit, findings, GEO, search, codefix"]
  D --> S{"Store pair"}
  S -->|self-host| SQ[("SQLite: data/okara.db")]
  S -->|hosted| PG[("Supabase Postgres + RLS")]
  D -->|guarded fetch| WEB["Your site, search and LLM APIs"]
  D -->|GitHub App| GH["Draft pull request"]
  CRON["Vercel Cron (hosted only)"] --> API

• One app, two modes. lib/features.ts chooses the mode. Self-host uses SQLite. Hosted uses Supabase, and a hosted deployment with missing Supabase config fails closed with HTTP 503.
• Store pairs. Each domain store has a SQLite file and a Supabase file, for example findingStore.ts and findingStoreSupabase.ts. The domain logic above them is shared and mostly pure.
• Finding lifecycle. new → acknowledged → fixing → fixed → verified | failed. Only evidence sets verified or failed: a Re-check, the automatic check, or a later GEO run. You cannot set them by hand.

stateDiagram-v2
  [*] --> new: audit / search / GEO gap
  new --> acknowledged
  acknowledged --> fixing
  fixing --> fixed: you mark it, or the fix PR merges
  fixed --> verified: Re-check passes (evidence)
  fixed --> failed: Re-check still detects it
  failed --> fixing
  verified --> fixing: regression
  note right of new: No longer detected is a flag, not a status.<br/>The finding waits for a Re-check.

For data flow, cron jobs, the GitHub App loop and setup state, see docs/architecture.md.

Security

• Auth. Supabase Auth. Server routes verify the user with auth.getUser() and do not trust a client-side session.
• Isolation. Row-level security on user tables. Server-trusted tables (profiles, settings, connections) are read-only to users. Project routes check that the signed-in user owns the project.
• Outbound requests. URLs that users can influence go through one guarded fetcher. It pins DNS, blocks private addresses, re-checks every redirect hop, and caps time and body size.
• OAuth. Google, Gmail and GitHub connect flows use a single-use, expiring state value. On hosted, only the user who started a flow can complete it. Email unsubscribe links use signed, expiring HMAC tokens.
• Keys. The operator's provider keys are never sent to a base URL that a user supplied (#170).
• External writes. Fix PRs and CMS publishes need a signed, expiring approval. PRs are drafts, and nothing auto-merges or auto-posts.
• Cron routes require a CRON_SECRET bearer token, compared in constant time.
• The Content-Security-Policy header is still report-only.

Read docs/security.md for details. To report a vulnerability, follow SECURITY.md and use GitHub private vulnerability reporting, not a public issue.

Plans and pricing

Hosted plans are Free, Lite and Pro, per website, and they are in beta. There is no payment gateway yet, so the paid plans have a waitlist at /pricing. The suggested beta prices are Lite $29/month ($24/month billed annually) and Pro $79/month ($66/month billed annually). Plan enforcement is off, so the plan limits are not active and hosted features are unlocked today. Self-host is always unlocked.

The full feature and limit matrix, generated from lib/domain/plans/planMatrix.ts, is in docs/plans-and-pricing.md.

Roadmap and known limits

Coming next, in order: finish the core loop (findings, re-check, GEO gaps), then audit depth, then hardening. Known limits today:

• Setup runs in your browser. Progress is saved and resumes when you return, but setup does not continue while the tab is closed.
• Shallow crawl. The audit covers 1 page and samples up to 8. A full crawl of hundreds of pages is not built.
• Scheduled jobs have limited coverage. Each cron is one time-boxed run per day (GEO: per week), so a large fleet of sites is covered slowly.
• Payments are not live. Plan limits are defined but not enforced.
• Limited GEO engines. Marlo measures Gemini grounded answers only, and labels the simulated stand-in as simulated.
• No automatic posting to X, LinkedIn or Reddit.
• Lead email checks use SMTP, which most cloud hosts block, so lead emails often show as unverified on hosted.
• E2E suite. The Playwright suite (layout, accessibility, vitals, visual) runs by hand, not in CI, and some accessibility and visual specs fail today.
• CSP is report-only.

Documentation

Contributing

Issues and pull requests are welcome. The rule for features matches the code: use real data or say plainly that it is not available. Never show a plausible-looking fake. If you add a feature, show its empty, loading and error states too.

npm test          # unit tests (node:test, tests/*.test.mts)
npm run lint      # ESLint
npm run build     # production build
npm run e2e       # Playwright (run `npx playwright install chromium` once first)

• Keep PRs small. Each PR should solve one problem end to end. Avoid broad refactors and new abstractions without a consumer.
• CI (.github/workflows/ci.yml) lints the files you changed, runs npm test (and fails if no tests ran), and runs a production build. Full-repo lint is informational only.
• Target main. The pr-base-guard job fails a PR whose base is another branch, unless the PR body says intentional-base.
• See docs/acceptance-gates.md for the definition of done.

License

Marlo is licensed under the GNU Affero General Public License v3.0. If you run a modified version as a network service, you must make its source available to the people who use it.