S.E.O Agent

Free, self-hosted SEO data and workflows for AI agents — keyword research, rank tracking, competitor insights, backlinks, site audits and AI visibility, exposed to Claude Code (and any MCP client) through an MCP server plus nine ready-made skills.

No account, no subscription, no telemetry. You run it, you own the data. The only external cost is DataForSEO, billed to you directly per API call.

Run it

Deploy to Railway: point a new service at this repo, mount a volume at /app/.wrangler, and set DATAFORSEO_API_KEY. railway.json handles the rest (it builds Dockerfile.selfhost and health-checks /api/health). Full walkthrough, including putting it on your own domain: Railway self-hosting.

To work on the code instead, run it directly:

cp .env.example .env.local    # set DATAFORSEO_API_KEY (base64 of login:password)
pnpm install --frozen-lockfile
pnpm run db:migrate:local
pnpm dev

App: http://localhost:3001 · MCP server: http://localhost:3001/mcp

Auth is disabled (AUTH_MODE=local_noauth). Any deployment reachable from the internet should set SELFHOST_BASIC_AUTH_USER and SELFHOST_BASIC_AUTH_PASSWORD, which put HTTP Basic auth in front of everything except /api/health and shared audit reports.

Docs: Railway self-hosting · DataForSEO key · Google Search Console · Local development

Related MCP server: UpgradeSEO MCP Server

Site audits

Crawl up to 500 pages and get back a prioritized list of what to fix. Alongside the usual technical checks (titles, meta descriptions, headings, canonicals, duplicates, broken links, orphans, redirect chains, thin content, Core Web Vitals via Lighthouse), each audit checks:

• Site files — robots.txt (a 5xx there stops Google crawling, so it is reported as critical; a 404 is not), an XML sitemap and whether robots.txt declares it, and llms.txt

• Favicon — declared, reachable, and in a format Google Search actually reads (it does not read SVG)

• Social previews — og:image present, absolute, large enough, and reachable

• Measurement tags — Google Analytics / Tag Manager, Search Console and Bing Webmaster verification tags in the served HTML

• Screenshots — how the page rendered on mobile and desktop, captured during the Lighthouse run

Share a report

Any finished audit can be published as a read-only link (/r/<token>), optionally behind a password. The recipient needs no account and can filter and sort the report but cannot change anything or reach the rest of the workspace. Links are revocable, and creating a new one retires the old.

Use it from Claude Code

/plugin marketplace add ahmadaimee/seo-agent
/plugin install seo-agent@seo-agent

The plugin's MCP entry defaults to http://localhost:3001/mcp. For a Railway (or any remote) instance set two environment variables on your machine:

• SEO_AGENT_MCP_URL — e.g. https://your-host/mcp

• SEO_AGENT_MCP_AUTH — e.g. Basic <base64 user:password> when Basic auth is on

Skills: /seo-project-setup, /keyword-research, /keyword-clustering, /competitor-analysis, /competitive-landscape, /seo-audit, /local-seo, /link-prospecting, /seo-coach.

What needs a key

Nothing is sent anywhere else. There is no usage heartbeat, no call counter and no phone-home; the telemetry the upstream project shipped was removed at the source.

Stack

Vite + TanStack Start (React) running on the Cloudflare Workers runtime (workerd), SQLite (D1) for storage, Drizzle migrations, an MCP server at /mcp. Deployed as a container image (Dockerfile.selfhost) on Railway.

License

MIT — see LICENSE.