Common Use Cases for OpenSEO: Complete Technical Guide to Self-Hosted SEO

OpenSEO is a self-hosted, pay-as-you-go SEO platform built on TypeScript that enables teams to perform keyword research, track search rankings, analyze backlinks, audit sites, and automate workflows via AI agents through a unified architecture of TanStack server functions and DataForSEO API integrations.

Understanding the common use cases for OpenSEO reveals how its modular design supports both manual SEO workflows and fully automated AI-driven processes. The every-app/open-seo repository implements these capabilities as typed server functions residing in src/serverFunctions/, backed by a Postgres/SQLite-compatible data layer defined in src/db/schema.ts.

Keyword Research and Management

Keyword research in OpenSEO generates ideas, fetches search volume, CPC, difficulty metrics, and tags them for content planning. The implementation centers on the researchKeywords server function in src/serverFunctions/keywords.ts, which wraps the DataForSEO Keyword Research endpoint.

The function uses createServerFn to provide RPC-style access:

import { researchKeywords } from '@/serverFunctions/keywords';

const result = await researchKeywords({
  seed: 'organic coffee',
  country: 'US',
  language: 'en',
});

Saved keyword management persists these findings for long-term strategy. The same file exports saveKeywords, getSavedKeywords, exportSavedKeywords, and tag management functions (updateSavedKeywordTag, deleteSavedKeywordTag). Validation schemas in src/types/schemas/keywords.ts ensure type safety across the API boundary, while the keywords table in src/db/schema.ts stores the data with support for custom tagging.

Rank Tracking Across Markets

Rank tracking monitors SERP positions for selected keywords across specific geographic markets. Configurations reside in the rank_tracking table (see src/db/schema.ts), populated via the useSaveConfigMutations hook in src/client/features/rank-tracking/useSaveConfigMutations.ts.

To add a tracking configuration:

import { useSaveConfigMutations } from '@/client/features/rank-tracking/useSaveConfigMutations';

const { mutate: addConfig } = useSaveConfigMutations();

addConfig({
  domain: 'example.com',
  keywords: ['organic coffee'],
  locations: [{ country: 'US', language: 'en' }],
});

A nightly scheduler defined in src/shared/rank-tracking.ts queries the DataForSEO SERP endpoint to update positions. Market resolution logic in src/shared/keyword-locations.ts ensures accurate localization for both the UI and background jobs.

Backlink Analysis and Site Audits

Backlink analysis retrieves domain profiles and evaluates link quality through the backlinks server function in src/serverFunctions/backlinks.ts. This function calls the DataForSEO Backlinks endpoint, returning referring domains, anchor text distributions, and authority scores.

Site audits combine internal crawling with Lighthouse performance metrics. The audit server function in src/serverFunctions/audit.ts orchestrates the crawl and delegates performance analysis to src/shared/lighthouse.ts. Results identify broken links, missing meta tags, and Core Web Vitals issues before persisting to the database.

Google Search Console Integration

GSC integration imports real-world performance data—impressions, clicks, and average positions—directly into the platform. The gsc server function in src/serverFunctions/gsc.ts handles OAuth authentication via Better-Auth (when AUTH_MODE=hosted), storing tokens securely while fetching search analytics data to correlate with rank tracking results.

AI-Agent Automation via MCP

A distinct use case for OpenSEO is AI-agent automation through the Model-Control-Protocol (MCP) layer. This exposes all SEO capabilities as tools that Claude Code, OpenClaw, Hermes, and other agents can invoke.

The MCP transport layer in src/server/mcp/transport.ts registers each server function under /mcp/tools. Agents receive context via the system prompt defined in src/server/features/sam/samSystemPrompt.ts, which describes available RPC endpoints.

An AI agent requesting a backlink report sends:

{
  "tool": "backlinks",
  "input": {
    "domain": "example.com",
    "limit": 100
  }
}

This architecture enables fully automated SEO workflows where agents research keywords, configure rank tracking, and audit sites without human intervention.

Self-Hosting and Deployment Options

Self-hosting represents a core use case for teams avoiding SaaS subscription fees. OpenSEO supports two primary deployment paths:

Docker deployment (documented in docs/SELF_HOSTING_DOCKER.md) provides a containerized environment with Postgres and complete environment isolation.

Cloudflare Workers (documented in docs/SELF_HOSTING_CLOUDFLARE.md) offers a serverless edge deployment:

pnpm run build
wrangler deploy

Authentication flexibility supports both paths. The src/lib/auth-mode.ts file defines multiple AUTH_MODE values: local development requires no authentication, while production deployments use Cloudflare Access JWT validation or Better-Auth email/password flows.

Local Development and Testing

For local development, OpenSEO supports both SQLite (via D1) and Postgres backends. Developers run migrations using:

pnpm run db:migrate:local

End-to-end testing relies on fixtures in src/e2e/fixtures/keyword-research-fixtures and seed scripts like scripts/seed-rank-tracking.ts. To launch a local instance without authentication:

cp .env.example .env.local
echo "DATAFORSEO_API_KEY=$(printf 'login:password' | base64)" >> .env.local
pnpm dev:agents

This starts the development server at http://open-seo.localhost:1355 as documented in docs/LOCAL_DEVELOPMENT.md.

Summary

• OpenSEO implements common SEO workflows as typed TanStack server functions in src/serverFunctions/, providing REST-like endpoints without boilerplate.
• Keyword research and rank tracking leverage DataForSEO APIs, with data normalized in src/db/schema.ts for both SQLite and Postgres compatibility.
• AI-agent automation via MCP (src/server/mcp/transport.ts) enables programmatic SEO workflows through standardized RPC calls.
• Flexible deployment supports Docker for traditional hosting and Cloudflare Workers for edge deployment, with auth modes ranging from none to OAuth.
• Validation occurs through Zod schemas in src/types/schemas/, ensuring type safety across client-server boundaries.

Frequently Asked Questions

What authentication methods does OpenSEO support for production deployments?

OpenSEO supports three authentication modes defined in src/lib/auth-mode.ts: local (no auth for development), cloudflare (JWT validation via Cloudflare Access), and hosted (email/password via Better-Auth with OAuth support for Google Search Console). The mode is controlled via the AUTH_MODE environment variable.

How does OpenSEO store data from DataForSEO API calls?

Results from DataForSEO endpoints populate normalized tables defined in src/db/schema.ts. Keyword research data stores in the keywords table with tagging support, while rank tracking configurations reside in rank_tracking. The schema supports both SQLite (for local/D1) and Postgres (for production) through a unified Drizzle ORM configuration.

Can OpenSEO run entirely without Docker?

Yes. The repository includes Cloudflare Workers deployment documentation in docs/SELF_HOSTING_CLOUDFLARE.md. Running pnpm run build generates a worker bundle compatible with Wrangler CLI deployment, eliminating the need for container infrastructure while maintaining the same server function capabilities.

What makes OpenSEO suitable for AI-agent integration?

OpenSEO implements the Model-Control-Protocol (MCP) in src/server/mcp/transport.ts, which exposes server functions as discoverable tools. The SAM system prompt (src/server/features/sam/samSystemPrompt.ts) provides agents with tool descriptions and schemas, allowing automated invocation of keyword research, backlink analysis, and audit functions without custom API wrappers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}