Simplify readme (#303)
This commit is contained in:
Ben Senescu
GitHub
parent
7cc4fa9aa5
commit
e9955b46cb
217
README.md
217
README.md
@ -30,7 +30,7 @@ Connect with any agent like Claude Code, OpenClaw or Hermes. We have pre-built s
|
||||
|
||||
## Hosted Version
|
||||
|
||||
If you not interested in self hosting, or just want to support the project, we also have a hosted version:
|
||||
If you're not interested in self hosting, or just want to support the project, we also have a hosted version:
|
||||
|
||||
[openseo.so](https://openseo.so)
|
||||
|
||||
@ -46,102 +46,38 @@ If you not interested in self hosting, or just want to support the project, we a
|
||||
## Main SEO Workflows
|
||||
|
||||
- Keyword research
|
||||
- Find topics worth targeting, estimate demand, and prioritize what to write next.
|
||||
- Rank tracking
|
||||
- Monitor keyword positions across desktop and mobile over time, with SERP feature detection.
|
||||
- Domain insights
|
||||
- Understand where your domain is gaining or losing visibility so you can focus on the pages that move revenue.
|
||||
- Competitor Insights
|
||||
- Backlinks
|
||||
- See who links to your site, which pages attract links, and where links are newly won or lost.
|
||||
- Site Audits
|
||||
- Catch technical issues early so your site is easier for search engines to crawl and rank.
|
||||
- AI brand visibility
|
||||
- See how your brand appears in AI answers, including competitor mentions and source coverage.
|
||||
- AI search prompt explorer
|
||||
- Track and explore the prompts people might use when they ask AI tools for recommendations in your market.
|
||||
- AI Visibility
|
||||
|
||||
## Community
|
||||
|
||||
Join Discord to chat: [Discord](https://discord.gg/c9uGs3cFXr)
|
||||
|
||||
Follow along for updates:
|
||||
|
||||
- Follow on X: https://x.com/bensenescu
|
||||
- Sign up for the mailing list on our website: [openseo.so](https://openseo.so)
|
||||
|
||||
## OpenSEO MCP
|
||||
|
||||
OpenSEO exposes an MCP server so AI agents can use your SEO data directly.
|
||||
|
||||
Connect Codex, Claude Code, Claude Desktop, or another MCP client to:
|
||||
Connect Claude Code, OpenClaw, Hermes or any other agent.
|
||||
|
||||
- Run keyword research
|
||||
- Inspect SERPs
|
||||
- Compare domains
|
||||
- Review backlinks
|
||||
- Work through SEO decisions from your editor or chat
|
||||
### Setup
|
||||
|
||||
In the app, open **AI & MCP** and copy your MCP server URL. Point your agent at whichever OpenSEO instance you use.
|
||||
|
||||
Hosted app:
|
||||
|
||||
```sh
|
||||
codex mcp add openseo --url https://app.openseo.so/mcp
|
||||
claude mcp add --transport http --scope user openseo https://app.openseo.so/mcp
|
||||
```
|
||||
|
||||
Cloudflare self-hosted:
|
||||
|
||||
```sh
|
||||
codex mcp add openseo --url https://your-openseo-domain.com/mcp
|
||||
claude mcp add --transport http --scope user openseo https://your-openseo-domain.com/mcp
|
||||
```
|
||||
|
||||
Local Docker:
|
||||
|
||||
```sh
|
||||
codex mcp add openseo --url http://localhost:3001/mcp
|
||||
claude mcp add --transport http --scope user openseo http://localhost:3001/mcp
|
||||
```
|
||||
|
||||
Approve the OpenSEO login when your agent asks.
|
||||
- Set up the app
|
||||
- Click "AI & Agents" in the header
|
||||
- Follow the instructions to connect to your agent
|
||||
|
||||
## OpenSEO Agent Skills
|
||||
|
||||
OpenSEO Agent Skills are reusable workflows for Codex and Claude Code. They guide your agent through SEO tasks and can use the OpenSEO MCP for live keyword, SERP, backlink, and domain data.
|
||||
OpenSEO Agent Skills are reusable workflows for your agent
|
||||
|
||||
### Installation Options
|
||||
|
||||
Install with `skills add`:
|
||||
|
||||
```sh
|
||||
npx skills add every-app/open-seo
|
||||
```
|
||||
|
||||
Auto-accept each OpenSEO skill:
|
||||
|
||||
```sh
|
||||
npx skills add every-app/open-seo --skill '*'
|
||||
```
|
||||
|
||||
Install for Claude Code only:
|
||||
|
||||
```sh
|
||||
npx skills add every-app/open-seo --skill '*' --agent claude-code
|
||||
```
|
||||
|
||||
Install for OpenAI Codex only:
|
||||
|
||||
```sh
|
||||
npx skills add every-app/open-seo --skill '*' --agent codex
|
||||
```
|
||||
|
||||
You can also pick skills directly from the GitHub repo and copy them into your agent's skills folder:
|
||||
|
||||
```sh
|
||||
git clone https://github.com/every-app/open-seo.git
|
||||
|
||||
# Codex
|
||||
mkdir -p ~/.codex/skills
|
||||
cp -R open-seo/.agents/skills/* ~/.codex/skills/
|
||||
|
||||
# Claude Code
|
||||
mkdir -p ~/.claude/skills
|
||||
cp -R open-seo/.agents/skills/* ~/.claude/skills/
|
||||
```
|
||||
|
||||
Start with `/seo-project-setup`. It will ask about your project and help configure your workspace.
|
||||
They guide your agent through SEO tasks and use the OpenSEO MCP so your agent makes better recommendations.
|
||||
|
||||
### Available Skills
|
||||
|
||||
@ -153,32 +89,25 @@ Start with `/seo-project-setup`. It will ask about your project and help configu
|
||||
- `competitor-analysis`
|
||||
- `link-prospecting`
|
||||
|
||||
### Installation Guide
|
||||
|
||||
Read our docs for how to install the skills:
|
||||
|
||||
https://openseo.so/docs/skills/setup
|
||||
|
||||
## Roadmap
|
||||
|
||||
Top priorities:
|
||||
|
||||
- Google Search Console Integration + MCP
|
||||
- Local SEO
|
||||
- Custom Reports for Clients
|
||||
- Improved and Scheduled Site Audits
|
||||
- Custom Reports for Clients
|
||||
- Local SEO
|
||||
- In App AI Agent
|
||||
- Support Multiple Projects
|
||||
|
||||
Our top priority is always refining the current product and making existing features better based on user feedback.
|
||||
|
||||
If something important is missing, please join the [Discord](https://discord.gg/c9uGs3cFXr) or email me at ben@openseo.so and request it.
|
||||
|
||||
## Community
|
||||
|
||||
Email me: ben@openseo.so
|
||||
|
||||
Join Discord to chat: [Discord](https://discord.gg/c9uGs3cFXr)
|
||||
|
||||
Follow along for updates:
|
||||
|
||||
- Sign up for the mailing list on our website: [openseo.so](https://openseo.so)
|
||||
- Follow on X: https://x.com/bensenescu
|
||||
|
||||
## Pricing / Costs
|
||||
|
||||
OpenSEO is totally free to use. It works by using DataForSEO's APIs, which is a paid third-party service unaffiliated with OpenSEO.
|
||||
@ -194,16 +123,9 @@ For cost estimates, see [DataForSEO API Cost Reference](#seo-api-cost-reference)
|
||||
|
||||
OpenSEO uses DataForSEO to fetch SEO data. You need an API key to connect OpenSEO to the service.
|
||||
|
||||
Backlinks requires one more step beyond the API key: you also need DataForSEO Backlinks enabled on your account (trial or paid subscription), then confirm access from the Backlinks page in OpenSEO.
|
||||
|
||||
1. Go to [DataForSEO API Access](https://app.dataforseo.com/api-access).
|
||||
2. Request API credentials by email (`API key by email` or `API password by email`).
|
||||
3. Use your DataForSEO login + API password, then base64 encode `login:password`:
|
||||
|
||||
```sh
|
||||
printf '%s' 'YOUR_LOGIN:YOUR_PASSWORD' | base64
|
||||
```
|
||||
|
||||
1. Go to [DataForSEO API Access](https://app.dataforseo.com/api-access?aff=255379).
|
||||
2. Click "Send by email" to get set your credentials.
|
||||
3. Copy the longer crendentials labelled "Base64" credentials.
|
||||
4. Set this as `DATAFORSEO_API_KEY` in your environment file:
|
||||
|
||||
- Docker self-hosting: `.env`
|
||||
@ -247,10 +169,6 @@ Quickstart:
|
||||
3. `docker compose up -d`
|
||||
4. Open `http://localhost:<PORT>` (default `3001`)
|
||||
|
||||
By default, `compose.yaml` pulls the published image from GHCR:
|
||||
|
||||
- `ghcr.io/every-app/open-seo:latest`
|
||||
|
||||
To update to the newest published image, pull first and then restart:
|
||||
|
||||
```sh
|
||||
@ -258,12 +176,6 @@ docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Or use a single command:
|
||||
|
||||
```sh
|
||||
docker compose up -d --pull always
|
||||
```
|
||||
|
||||
For more info, see [`docs/SELF_HOSTING_DOCKER.md`](./docs/SELF_HOSTING_DOCKER.md).
|
||||
|
||||
## Cloudflare Self-Hosting
|
||||
@ -301,69 +213,9 @@ As of February 26, 2026, DataForSEO’s public docs/pricing pages say:
|
||||
|
||||
That means you can try OpenSEO for free with the starter credit, then decide if/when to top up.
|
||||
|
||||
### Pricing sources
|
||||
|
||||
- DataForSEO SERP API pricing: https://dataforseo.com/apis/serp-api/pricing
|
||||
- DataForSEO Keywords Data API pricing: https://dataforseo.com/pricing/dataforseo-labs/dataforseo-google-api
|
||||
- DataForSEO Backlinks pricing: https://dataforseo.com/pricing/backlinks/backlinks
|
||||
- DataForSEO Lighthouse API docs: https://docs.dataforseo.com/v3/on_page/lighthouse/overview/
|
||||
|
||||
### 1) Rank tracking
|
||||
|
||||
Rank tracking is fully configurable, and there are live in-app estimates since cost depends on the settings you select: number of keywords, devices, how many SERP pages deep you check, and how often it runs (weekly or daily).
|
||||
|
||||
Scheduled checks run through DataForSEO's task queue, which is significantly cheaper than live SERP lookups.
|
||||
|
||||
~$1/month example:
|
||||
|
||||
- 100 keywords
|
||||
- 1 device type (Mobile or Desktop)
|
||||
- Search 5 pages deep
|
||||
- Weekly schedule
|
||||
|
||||
Searching ten pages deep costs about 8x more than one page, tracking both device types costs 2x more, and a daily schedule costs about 7x a weekly one.
|
||||
|
||||
### 2) Site audit
|
||||
|
||||
- $0.01 per 20 pages audited with Lighthouse
|
||||
|
||||
### 3) Keyword research (`related` mode)
|
||||
|
||||
- Current billed cost pattern (from account usage logs):
|
||||
- `0.02 + (0.0001 x returned_keywords)` USD
|
||||
- Default app setting: `150` results per search (`$0.035` each).
|
||||
- Available result tiers:
|
||||
- 150 results = `$0.035`
|
||||
- 300 results = `$0.05`
|
||||
- 500 results = `$0.07`
|
||||
|
||||
### 4) Domain overview
|
||||
|
||||
- Standard domain overview request (with top 200 ranked keywords): `$0.0401` per domain.
|
||||
- General formula if needed:
|
||||
- `0.0201 + (0.0001 x ranked_keywords_returned)` USD
|
||||
|
||||
### 5) Backlinks search
|
||||
|
||||
> [!NOTE]
|
||||
> There is a 2 week free trial, but then DataForSEO requires a $100/month commitment for this API. You can access this data for just $10/month through [openseo.so](https://openseo.so). Soon, we'll let you use an OpenSEO API key so that you can call our API from your self hosted instance.
|
||||
|
||||
- Backlinks search costs about `$0.06` for a domain or `$0.04` for a page.
|
||||
- Opening extra tabs like `Referring Domains` or `Top Pages` adds about `+$0.02` each.
|
||||
- Exact cost can vary slightly based on returned rows and DataForSEO pricing.
|
||||
|
||||
### 6) AI Search — Brand Lookup
|
||||
|
||||
- One lookup = 6 DataForSEO AI Optimization calls (`aggregated_metrics` + `top_pages` + `mentions_search` across ChatGPT and Google AI Overview): up to about `$0.85` per lookup.
|
||||
- `aggregated_metrics`: `$0.101` per platform.
|
||||
- `top_pages`: page-ranked cited sources per platform.
|
||||
- `mentions_search`: row-priced; `$0.20` per platform at the app's full 100-row sample (lower-volume brands return fewer rows and cost less).
|
||||
- Adding competitors (Share of Voice) adds 2 `cross_aggregated_metrics` calls: about `$0.10` each, `$0.20` total.
|
||||
- Results are cached for 24 hours, so repeating the same lookup (same target + competitor set) is free within a day.
|
||||
- Re-measure anytime with `pnpm billing:brand-lookup --target=example.com --competitors=a.com,b.com --confirmLive=true`.
|
||||
|
||||
### Planning examples
|
||||
|
||||
- Track 100 keywords weekly at depth 50: `~$1.20/month`
|
||||
- 100 keyword research requests at the default 150 results: `$3.50`
|
||||
- 100 keyword research requests at 500 results each: `$7.00`
|
||||
- 100 domain overviews (200 ranked keywords each): `$4.01`
|
||||
@ -371,3 +223,10 @@ Searching ten pages deep costs about 8x more than one page, tracking both device
|
||||
- 100 backlinks page searches at current defaults before opening extra tabs: about `$4.30`
|
||||
- 100 fully explored backlinks domain searches: about `$10.94`
|
||||
- 100 fully explored backlinks page searches: about `$8.61`
|
||||
|
||||
### Pricing sources
|
||||
|
||||
- DataForSEO SERP API pricing: https://dataforseo.com/apis/serp-api/pricing
|
||||
- DataForSEO Keywords Data API pricing: https://dataforseo.com/pricing/dataforseo-labs/dataforseo-google-api
|
||||
- DataForSEO Backlinks pricing: https://dataforseo.com/pricing/backlinks/backlinks
|
||||
- DataForSEO Lighthouse API docs: https://docs.dataforseo.com/v3/on_page/lighthouse/overview/
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user