dispatchseo

<p align="center">
  <a href="https://dispatchseo.com">
    <img src="src/app/icon.png" width="90" alt="DispatchSEO logo">
  </a>
</p>

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

<p align="center"><b>Turn Claude Code into your SEO manager.</b></p>

<p align="center">
  <a href="LICENSE"><img src="docs/buttons/license-agpl.svg" alt="License: AGPL-3.0"></a>
</p>

<p align="center">
  <a href="https://dispatchseo.com">Website</a>
  &nbsp;&middot;&nbsp;
  <a href="https://dispatchseo.com/docs">Quickstart</a>
  &nbsp;&middot;&nbsp;
  <a href="https://dispatchseo.com/docs/docker-compose">Self-hosting guide</a>
  &nbsp;&middot;&nbsp;
  <a href="https://github.com/NeoZi12/dispatchseo/discussions">Discussions</a>
  &nbsp;&middot;&nbsp;
  <a href="https://dispatchseo.com">Hosted version</a>
</p>

<p align="center">
The open-source alternative to SEObot and Outrank, built for Claude Code.
Other SEO tools learn about your product by crawling your homepage. Your
Claude Code already knows your product, because it probably built half of it.
DispatchSEO gives that agent the missing pieces: a research playbook, a
content pipeline that ships pull requests, rank tracking, and a dashboard
where you stay in control.
</p>

<p align="center">Self-hosting is one command on any machine with Docker - on
a VPS, <code>ssh</code> in first, then run this there instead of on your
own computer. Run it from any plain folder (not inside your website's
repo; it creates its own <code>dispatchseo</code> folder):</p>

```bash
git clone https://github.com/NeoZi12/dispatchseo &&
  cd dispatchseo &&
  sh start.sh
```

<p align="center">When it finishes it prints your dashboard URL - open it
and the setup wizard takes it from there. Your laptop is fine for trying
it out, but <b>we highly recommend a machine that stays on</b> for real
use - a $5 VPS, a Raspberry Pi, a desktop that never sleeps. The
<a href="https://dispatchseo.com/docs/vps">VPS guide</a> has a shorter
one-line installer plus your own domain with automatic HTTPS;
<a href="https://dispatchseo.com/docs/docker-compose">the local guide</a>
explains exactly what's lost on a laptop and what isn't. On Windows,
paste this in WSL or Git Bash.</p>

<p align="center">Step-by-step walkthroughs:
<a href="https://dispatchseo.com/docs/docker-compose">on your computer</a>
&nbsp;·&nbsp;
<a href="https://dispatchseo.com/docs/vps">on a VPS</a></p>

<p align="center"><i>Self-hosted has zero feature limitations. Everything the
paid cloud will do, this repo does today, in your own accounts, at $0.</i></p>

<p align="center">
  <a href="https://www.youtube.com/watch?v=1gCXPxPqfy0">
    <img src="https://img.youtube.com/vi/1gCXPxPqfy0/maxresdefault.jpg" alt="DispatchSEO preview video - the dashboard, the queue, and a pipeline-built pull request, walked through end to end">
  </a>
  <br>
  <sub>▶ Watch the preview</sub>
</p>

## How it works

1. **Your agent researches.** Claude Code connects to DispatchSEO over MCP,
   reads the served playbook, and mines keywords from your Search Console
   data, Google Autocomplete, and what it already knows about your product.
   Ideas land in a queue with the reasoning attached.
2. **You approve, or don't.** Each idea is a card on the dashboard: the
   keyword, why it's winnable, the angle. Approve, reject, or reorder.
   Prefer full autopilot? Flip on auto mode and skip the queue entirely.
3. **The pipeline builds.** Every morning a GitHub Action picks the oldest
   approved idea and builds it into a real pull request against your site's
   repo: a guide or a small free tool, checked against the live SERP and run
   through a sameness reviewer so page twelve doesn't read like page three.
4. **It tracks what happened.** Daily rank checks, hourly Search Console
   snapshots, index verification, and a journey view that tells you which
   SEO stage you're actually in. When a scheduled job breaks, you get a red
   banner and an email instead of silence.

The backend is deliberately boring: state, scheduling, and an approval gate.
The thinking happens in your agent, where your product knowledge already
lives.

<table>
  <tr>
    <td colspan="2"><img src="docs/screenshots/home.png" alt="The dashboard Home: journey stage, publishing pace, and live Search Console stats for a connected site"></td>
  </tr>
  <tr>
    <td><img src="docs/screenshots/queue.png" alt="The queue: keyword ideas with volume and difficulty, each waiting for approval or set to auto"></td>
    <td><img src="docs/screenshots/guide-pr.png" alt="A pull request the pipeline built: target keyword, SERP gate verdict, archetype, and information-gain asset, all named in the description"></td>
  </tr>
  <tr>
    <td><img src="docs/screenshots/search-traffic.png" alt="Search traffic: clicks and impressions from Google Search Console, snapshotted hourly"></td>
    <td><img src="docs/screenshots/rankings.png" alt="Keyword rankings: daily position checks with 30-day trend sparklines"></td>
  </tr>
</table>

## What's in the box

- **MCP server** with ~40 tools: the queue, keywords, rankings, pages, GSC
  stats, backlink prospects, trend topics, site profile. Anything the
  dashboard can do, your agent can do over MCP; parity between the two is a
  hard rule in this codebase.
- **Trend radar**: scan for rising topics in your niche, expand a topic into
  concrete guide angles, and queue the good ones.
- **Guide and tool builders**: guides publish on a pace matched to your
  site's age (so a three-week-old blog doesn't suddenly ship 30 posts);
  free-tool ideas build on approval.
- **Backlink playbook**: a prospect list prefilled with your product's copy,
  tracked per submission.
- **Multi-site**: one deployment manages any number of sites. Each project
  gets its own MCP token, its own data, its own settings.
- **A password-gated dashboard** for the one human in the loop.

## What it costs to run

Nothing, unless you want paid data. The tiers stack:

| Tier | Price | What you get |
| --- | --- | --- |
| Search Console only | $0 | Rankings from GSC, keyword ideas from Autocomplete plus your own impression data |
| + SerpApi free key | $0 | Live SERP checks, real positions weekly (250 free searches/month) |
| + DataForSEO | pay per call | Search volume, keyword difficulty, domain rating |

Free mode finds keywords you can win. Paid mode also knows which ones are
worth winning.

## What you need

- Your site's source in a GitHub repo. The pipeline ships content as pull
  requests, so git-based sites only; WordPress won't work.
- A Claude subscription with Claude Code. Your agent is the engine and it
  runs on your existing plan.
- A machine with Docker (~1 GB RAM). A laptop works for a test drive, but
  **we highly recommend a machine that stays on** for day-to-day use - a $5
  VPS, a Raspberry Pi, or a home server. Schedules only run while the
  machine is awake.
- Google Search Console access to your site.

## Quick start

The one command above is the whole install
([the docs](https://dispatchseo.com/docs) are the full guide). Database,
migrations, schedules, and a headless Claude Code builder are all bundled;
open the dashboard and the setup wizard takes over. Nothing on the internet
needs to reach your machine, so there is no domain or port forwarding to
set up.

The last step is pasting one command into Claude Code inside your site's
repo. Your agent does the rest of the install itself, including writing its
own workflow files and setting its own secrets.

There's also an [llms.txt](public/llms.txt) and a [SKILL.md](SKILL.md) if
you'd rather point an agent at this repo and let it figure the setup out.

## Developing (from source)

```bash
git clone https://github.com/NeoZi12/dispatchseo
cd dispatchseo
pnpm install
cp .env.local.example .env.local
pnpm dev
```

This is the contributor path, not the way to self-host (that's the Docker
command above). Fill in `.env.local` (Supabase + the three secrets) before
starting, then open the dashboard on **localhost:3000**.

`pnpm build` is the typecheck - run it before opening a PR. There is no
separate lint or test setup.

## Cloud version

There's a hosted version for people who'd rather not run a machine: we host
it, bundle the SERP + volume data into one bill, and replace the Google
service-account ritual with one click. It's at
[dispatchseo.com](https://dispatchseo.com). Self-hosting stays
feature-complete either way; the cloud sells convenience, not capability.

## Architecture, briefly

Next.js App Router, Postgres for state (a bundled container when
self-hosted, Supabase in the cloud version), `mcp-handler` for the MCP
server at `/api/mcp`. Schedules and builds run in-stack (cron + builder
containers) or on GitHub Actions. One deployment is multi-tenant: the MCP
bearer token selects the project, crons loop over all projects, the
dashboard switches with a cookie.
[CLAUDE.md](CLAUDE.md) has the full conventions; it's written for agents,
which turns out to make it decent documentation for people.

## Contributing

Issues before PRs, and you must understand every line you submit, including
the AI-assisted ones. Details in [CONTRIBUTING.md](CONTRIBUTING.md).
Questions go to [Discussions](https://github.com/NeoZi12/dispatchseo/discussions);
vulnerabilities go through [private reporting](SECURITY.md).

## License

[AGPL-3.0](LICENSE). Use it, self-host it, fork it. If you run a modified
version as a service, share the source. That's the whole deal.

---

[![Star History Chart](https://api.star-history.com/svg?repos=NeoZi12/dispatchseo&type=Date)](https://star-history.com/#NeoZi12/dispatchseo)