# OpenSEO Features: Complete Guide to the Open-Source SEO Toolkit

> Explore OpenSEO features: keyword research, rank tracking, competitor analysis, backlink monitoring, site audits, and AI visibility. This open-source SEO toolkit offers enterprise-grade capabilities.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: tutorial
- Published: 2026-07-29

---

**OpenSEO delivers enterprise-grade SEO capabilities—including keyword research, rank tracking, competitor analysis, backlink monitoring, site audits, and AI visibility—through a type-safe, modular TypeScript architecture that supports both REST APIs and MCP server integration.**

OpenSEO is a modern open-source SEO platform maintained by the every-app organization that provides the core functionality of commercial tools like Semrush and Ahrefs while remaining fully self-hostable. The codebase emphasizes strict TypeScript typing with Zod validation, a clean separation between server functions and client hooks, and native support for AI agents via the Message Control Protocol (MCP).

## Core SEO Workflows

OpenSEO organizes its functionality around six primary SEO workflows defined in the project README (lines 28-35). Each workflow maps to specific server-side implementations in `src/serverFunctions/` and corresponding client-side data fetching hooks.

### Keyword Research

The **keyword research** module generates search volume, CPC, and keyword difficulty data by integrating with the DataForSEO API. Client components consume this data through the `useKeywordResearchData` hook located in [`src/client/features/keywords/hooks/useKeywordResearchData.ts`](https://github.com/every-app/open-seo/blob/main/src/client/features/keywords/hooks/useKeywordResearchData.ts), which performs a `GET` request to `/api/v1/projects/${projectId}/keyword-research`. The endpoint uses Zod schemas defined in `src/types/` to validate incoming query parameters and outgoing response shapes.

### Rank Tracking

**Rank tracking** functionality schedules periodic SERP position checks for monitored keywords and maintains historical ranking data. The business logic resides in [`src/shared/rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/rank-tracking.ts), which exports Zod schemas for request validation and provides utilities for building DataForSEO task queues. The server-side endpoint handling these operations is implemented in the serverFunctions layer, queuing tasks to DataForSEO's API and persisting results via Drizzle ORM.

### Competitor Insights

OpenSEO retrieves competitor domain metrics, organic traffic estimates, and top-performing keywords through the **competitor insights** feature. This implementation adapts Ahrefs-style API responses to OpenSEO's internal data model in [`src/serverFunctions/ahrefs.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/ahrefs.ts), allowing users to analyze rival domains without third-party subscription lock-in.

### Backlinks

The **backlinks** module collects comprehensive link profiles, including anchor text distribution, referring domain authority, and link-type categorization (follow vs. nofollow). Server-side logic in [`src/serverFunctions/backlinks.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/backlinks.ts) exposes endpoints consumed by the UI at `/api/v1/projects/:projectId/backlinks`, enabling real-time analysis of site authority metrics.

### Site Audits

Technical SEO audits run via the **site audits** feature, which aggregates crawlability metrics, indexability status, and Lighthouse performance data. The coordinator logic lives in [`src/serverFunctions/audit.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/audit.ts), while performance-specific utilities are wrapped in [`src/shared/lighthouse.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/lighthouse.ts). These components generate comprehensive reports covering page speed, mobile usability, and structured data validation.

### AI Visibility

The **AI visibility** workflow uses OpenAI-compatible prompts to transform raw SEO metrics into strategic recommendations. Server-side pipelines in [`src/serverFunctions/ai-search.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/ai-search.ts) and location-aware keyword processing in [`src/shared/keyword-locations.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/keyword-locations.ts) enable AI agents to interpret ranking fluctuations and suggest content optimizations.

## MCP Server and Agent Integration

OpenSEO distinguishes itself from traditional SEO tools by exposing all functionality through an **MCP server** (Message Control Protocol) defined in [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts). This JSON-RPC-style interface allows AI agents such as Claude Code or custom automation scripts to invoke SEO workflows directly.

Agents can trigger rank tracking scans, fetch keyword data, or initiate site audits without interacting with the React frontend. The MCP handler routes incoming actions to the appropriate service layer—for example, mapping a `trackRank` action to the rank-tracking service in [`src/shared/rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/rank-tracking.ts).

## Technical Architecture

OpenSEO follows a **TanStack server-function → service → repository** pattern that ensures type safety from database to client.

### Type-Safe Data Layer

All external inputs are validated using **Zod** schemas, preventing runtime errors from malformed DataForSEO responses. The database layer uses Drizzle ORM (configured in [`drizzle.config.ts`](https://github.com/every-app/open-seo/blob/main/drizzle.config.ts)) and supports both SQLite for local development and PostgreSQL for production deployments.

### Modular Server Functions

Each major feature is isolated in its own `src/serverFunctions/` file—such as [`gsc.ts`](https://github.com/every-app/open-seo/blob/main/gsc.ts) for Google Search Console integration, [`domain.ts`](https://github.com/every-app/open-seo/blob/main/domain.ts) for domain management, and [`billing.ts`](https://github.com/every-app/open-seo/blob/main/billing.ts) for subscription handling. This modularity keeps the HTTP layer thin and allows individual functions to be tested or deployed independently.

## Self-Hosting Deployment Options

OpenSEO supports two primary self-hosting strategies that give users full data sovereignty.

- **Docker deployment** provides a single-container setup optimized for local development or small teams. Configuration files and setup instructions are documented in [`docs/SELF_HOSTING_DOCKER.md`](https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_DOCKER.md).

- **Cloudflare Workers deployment** offers a globally distributed, edge-computed architecture suitable for high-traffic scenarios. Advanced configuration details reside in [`docs/SELF_HOSTING_CLOUDFLARE.md`](https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_CLOUDFLARE.md).

Both approaches require a **DataForSEO API key**, which users provide via environment variables—the key is never hardcoded in the repository source.

## Practical Code Examples

The following examples demonstrate how to interact with OpenSEO's API endpoints and MCP interface using TypeScript.

### Fetching Keyword Research Data

To retrieve keyword suggestions programmatically, call the REST endpoint used by the internal React hooks:

```typescript
// Replace PROJECT_ID with your actual project UUID
const response = await fetch(
  `/api/v1/projects/${PROJECT_ID}/keyword-research?keyword=coffee&location=us`
);
const data = await response.json();
console.log('Keyword volume and difficulty:', data);

```

This endpoint leverages the `useKeywordResearchData` hook pattern and validates responses against Zod schemas in [`src/types/schemas/keywords.ts`](https://github.com/every-app/open-seo/blob/main/src/types/schemas/keywords.ts).

### Triggering Rank Tracking via MCP

AI agents can queue rank tracking tasks by posting to the MCP endpoint:

```typescript
await fetch('https://your-openseo-instance.com/mcp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    action: 'trackRank',
    projectId: 'PROJECT_ID',
    keywords: ['coffee', 'espresso'],
    location: 'us',
    devices: ['desktop', 'mobile']
  })
});

```

The request is routed through [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) to the rank-tracking implementation in [`src/shared/rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/rank-tracking.ts), which schedules tasks with DataForSEO.

### Running Site Audits from the Client

Client components can trigger technical audits using TanStack Query:

```tsx
import { useQuery } from '@tanstack/react-query';

function AuditButton({ projectId }: { projectId: string }) {
  const { data, refetch } = useQuery(
    ['siteAudit', projectId],
    () => fetch(`/api/v1/projects/${projectId}/audit`).then(r => r.json())
  );

  return <button onClick={() => refetch()}>Run Technical Audit</button>;
}

```

This invokes the audit coordinator in [`src/serverFunctions/audit.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/audit.ts), which aggregates Lighthouse performance data and backlink metrics into a unified report.

## Summary

- OpenSEO provides six core SEO workflows: keyword research, rank tracking, competitor insights, backlinks, site audits, and AI visibility.
- The architecture uses TypeScript with Zod validation and Drizzle ORM, supporting both SQLite and PostgreSQL backends.
- A built-in MCP server in [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) enables AI agents to automate SEO tasks via JSON-RPC calls.
- Self-hosting options include Docker for simplicity and Cloudflare Workers for distributed edge deployment.
- Code is organized into modular server functions ([`src/serverFunctions/ahrefs.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/ahrefs.ts), [`audit.ts`](https://github.com/every-app/open-seo/blob/main/audit.ts), [`backlinks.ts`](https://github.com/every-app/open-seo/blob/main/backlinks.ts), etc.) that maintain strict separation between API endpoints and business logic.

## Frequently Asked Questions

### What APIs does OpenSEO use for SEO data?

OpenSEO integrates primarily with the **DataForSEO API** to retrieve keyword volumes, SERP rankings, and backlink profiles. Users must provide their own DataForSEO API key via environment variables, as the open-source codebase does not include proprietary data sources.

### Can I self-host OpenSEO without using Docker?

Yes. While Docker provides the simplest path for local deployment, OpenSEO also supports **Cloudflare Workers** for serverless edge deployment. Documentation for the Cloudflare approach is available in [`docs/SELF_HOSTING_CLOUDFLARE.md`](https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_CLOUDFLARE.md), offering a scalable alternative for production environments.

### How does the MCP server enable AI automation?

The MCP server exposed in [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) implements a JSON-RPC interface that translates agent commands into SEO workflow executions. AI agents can invoke actions like `trackRank` or fetch keyword research data without browser automation, directly accessing the business logic in [`src/shared/rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/rank-tracking.ts) and related modules.

### Is OpenSEO suitable for large-scale agency use?

Yes. The modular **server-function → service → repository** architecture allows horizontal scaling, particularly when deployed on Cloudflare's edge network. The Drizzle ORM configuration supports PostgreSQL for high-concurrency scenarios, and the type-safe Zod schemas prevent data corruption across distributed teams.