📈 Marketers MCP 📈

Your AI assistant just became an SEO expert.

Token-optimized SEO tools for AI agents. 19 tools. One MCP server. Zero context window waste.

---

Get Started •
Why Marketers MCP •
Tools •
Configuration •
Examples

---

The Pitch

Your AI spends half its context window on raw API responses it can barely parse. marketers-mcp fixes this. 19 SEO tools powered by DataForSEO, each returning token-optimized previews (300-500 tokens) with download URLs for the full dataset. Ask your AI to research keywords, audit backlinks, or spy on competitors — it queries DataForSEO directly and gives you actionable insights without drowning in data.

🔑 Keywords

Seed keywords → goldmine of opportunities. Volume, difficulty, CPC, trends — all in one call.

🔗 Backlinks

Full backlink profile analysis. Referring domains, anchor text, new/lost links, competitor comparisons.

📊 SERP Analysis

SERP features, ranking positions, content analysis. See what Google actually shows users.

🏢 Competitor Intel

Find competitors, compare domains head-to-head, discover gaps in your strategy.

$3

``You: "Find keywords related to 'email marketing' with volume > 1000"

┌──────────────┐ ┌──────────────────┐ ┌────────────────┐ │ AI Agent │ ──── │ marketers-mcp │ ──── │ DataForSEO │ │ (Claude) │ │ MCP Server │ │ API │ └──────────────┘ └──────────────────┘ └────────────────┘

AI receives (300-500 tokens): { "summary": "Found 247 keywords for 'email marketing'. Top: 'email marketing tools' (14,800/mo)", "preview": [ ...top 10 keywords with volume, difficulty, CPC... ], "stats": { "totalRows": 247, "avgVolume": 3200 }, "downloadUrl": "https://r2.example.com/full-dataset.json?presigned...", "nextSteps": ["analyze_keywords for difficulty deep-dive", "analyze_serp for ranking intent"] }

Full dataset (247 rows) available via download URL — AI never chokes on data.`

---

`Why Marketers MCP`

❌ Without Marketers MCP	✅ With Marketers MCP
1. Open SEMrush, Ahrefs, or Moz 2. Run queries, wait for results 3. Export CSVs 4. Copy-paste data into AI chat 5. Hit token limits on large datasets 6. Get fragmented, incomplete analysis 7. Repeat for every follow-up question	1. Ask your AI about any SEO topic 2. AI calls DataForSEO directly via MCP 3. Gets token-optimized preview (300-500 tokens) 4. Downloads full dataset when needed via R2 URL 5. Chains multiple tools for complete workflows 6. One conversation. Full analysis. No tab-switching.

❌ Without Marketers MCP

✅ With Marketers MCP

1. Open SEMrush, Ahrefs, or Moz
2. Run queries, wait for results
3. Export CSVs
4. Copy-paste data into AI chat
5. Hit token limits on large datasets
6. Get fragmented, incomplete analysis
7. Repeat for every follow-up question

1. Ask your AI about any SEO topic
2. AI calls DataForSEO directly via MCP
3. Gets token-optimized preview (300-500 tokens)
4. Downloads full dataset when needed via R2 URL
5. Chains multiple tools for complete workflows
6. One conversation. Full analysis. No tab-switching.

---

`Get Started`

`$3`

> Note: This package is not yet published to npm. You must clone and build locally.

`bash git clone https://github.com/yigitkonur/mcp-marketers.git cd mcp-marketers npm install npm run build`

`$3`

Sign up at dataforseo.com and grab your API login and password from the dashboard.

`$3`

Add this to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json

`json { "mcpServers": { "seo": { "command": "node", "args": ["/absolute/path/to/mcp-marketers/build/index.js"], "env": { "DATAFORSEO_USERNAME": "your_username", "DATAFORSEO_PASSWORD": "your_password", "R2_ACCOUNT_ID": "optional_r2_account_id", "R2_ACCESS_KEY_ID": "optional_r2_access_key", "R2_SECRET_ACCESS_KEY": "optional_r2_secret", "R2_BUCKET": "optional_r2_bucket" } } } }`

Restart Claude Desktop after saving the config.

`$3`

`bash claude mcp add seo \ -e DATAFORSEO_USERNAME=your_username \ -e DATAFORSEO_PASSWORD=your_password \ -- node /absolute/path/to/mcp-marketers/build/index.js`

`$3`

Add to your .cursor/mcp.json or Windsurf MCP config:

---

`Transport Modes`

Marketers MCP supports three transport modes:

| Mode | Use Case | How to Start | |------|----------|-------------| | STDIO (default) | Claude Desktop, Cursor, Windsurf |npx mcp-marketers| | HTTP Streamable | Self-hosted, Docker, LAN sharing |MCP_TRANSPORT=http npx mcp-marketers| | Cloudflare Workers | Serverless, globally distributed | Already deployed ↓ |

`$3`

A remote MCP endpoint is deployed and ready to use:

`https://mcp-marketers.seodoold.workers.dev/mcp`

Connect from any MCP client that supports HTTP Streamable transport:

`json { "mcpServers": { "marketers-remote": { "type": "streamable-http", "url": "https://mcp-marketers.seodoold.workers.dev/mcp" } } }`

`$3`

`bash

`Start on default port 3001`


MCP_TRANSPORT=http npx mcp-marketers
Custom port

MCP_TRANSPORT=http MCP_PORT=8080 npx mcp-marketers

`json { "mcpServers": { "marketers-http": { "type": "streamable-http", "url": "http://localhost:3001/mcp" } } }`

---

`Tool Reference`

🔑
Keywords
research analyze compare 🌐
Domains
analyze competitors compare 🔗
Backlinks
analyze compare monitor 📊
SERP & Content
serp content suggestions 🏢
Business
analyze find 📱
App
analyze ⚙️
Utilities
locations categories languages download

`$3`

| # | Tool | Category | Description | |---|------|----------|-------------| | 1 |research_keywords| Keywords | Discover keyword ideas from seed keywords across multiple data sources | | 2 |analyze_keywords| Keywords | Get detailed metrics — difficulty, volume, CPC, trends — for specific keywords | | 3 |compare_keywords| Keywords | Side-by-side keyword comparison with relative metrics | | 4 |analyze_domain| Domains | Full domain SEO overview — traffic, top pages, organic keywords | | 5 |analyze_competitors| Domains | Discover competing domains and their overlap with yours | | 6 |compare_domains| Domains | Head-to-head comparison of 2-5 domains on key SEO metrics | | 7 |analyze_backlinks| Backlinks | Backlink profile analysis — referring domains, anchors, link types | | 8 |compare_backlinks| Backlinks | Compare backlink profiles between domains | | 9 |monitor_backlinks| Backlinks | Track new and lost backlinks over time | | 10 |analyze_serp| SERP & Content | SERP feature analysis — featured snippets, PAA, local packs, rankings | | 11 |analyze_content| SERP & Content | Content analysis for target keywords — word count, readability, topics | | 12 |get_suggestions| SERP & Content | Autocomplete and related search suggestions | | 13 |analyze_business| Business | Business listing data — reviews, ratings, hours, contact info | | 14 |find_businesses| Business | Search businesses by category, location, and keyword | | 15 |analyze_app| App | App Store and Google Play metrics — ratings, reviews, rankings | | 16 |get_locations| Utilities | List all available target locations with codes | | 17 |get_categories| Utilities | Browse business and content categories | | 18 |get_languages| Utilities | List supported languages with codes | | 19 |download_data | Utilities | Retrieve full datasets from R2 presigned URLs |

---


🔑 Keywords Tools — research, analyze, compare

#### research_keywordsDiscover keyword ideas from seed keywords using multiple discovery methods. Supports Google, Bing, and Clickstream data sources.

`json research_keywords({ "keywords": ["seo tools"], "dataType": "suggestions", "minVolume": 1000, "location": "United States" })`

#### analyze_keywordsGet detailed keyword metrics including difficulty scores, search volume, CPC, competition, and historical trends.

`json analyze_keywords({ "keywords": ["email marketing", "content marketing"], "location": "United States" })`

#### compare_keywordsCompare keywords side-by-side on volume, difficulty, CPC, and trend data for prioritization.

`json compare_keywords({ "keywords": ["react vs vue", "angular vs svelte"], "location": "United States" })`


🌐 Domains Tools — analyze, competitors, compare

#### analyze_domainFull domain SEO overview including organic traffic estimates, top ranking pages, keyword distribution, and technology stack.

`json analyze_domain({ "domain": "example.com", "location": "United States" })`

#### analyze_competitorsDiscover which domains compete with yours for the same organic keywords and traffic.

`json analyze_competitors({ "domain": "example.com", "location": "United States" })`

#### compare_domainsHead-to-head comparison of 2-5 domains on traffic, keyword overlap, backlink strength, and domain authority.

`json compare_domains({ "domains": ["site-a.com", "site-b.com", "site-c.com"], "location": "United States" })`


🔗 Backlinks Tools — analyze, compare, monitor

#### analyze_backlinksComprehensive backlink profile analysis — referring domains, anchor text distribution, dofollow/nofollow ratio, link types.

`json analyze_backlinks({ "target": "example.com", "sortBy": "rank", "limit": 100 })`

#### compare_backlinksCompare backlink profiles between two or more domains to find link-building opportunities.

`json compare_backlinks({ "targets": ["site-a.com", "site-b.com"] })`

#### monitor_backlinksTrack newly acquired and recently lost backlinks for any domain.

`json monitor_backlinks({ "target": "example.com", "mode": "new" })`


📊 SERP & Content Tools — serp, content, suggestions

#### analyze_serpAnalyze SERP features for a keyword — featured snippets, People Also Ask, local packs, knowledge panels, and organic rankings.

`json analyze_serp({ "keyword": "best crm software", "location": "United States" })`

#### analyze_contentContent analysis for target keywords — typical word count, readability scores, topic coverage among top-ranking pages.

`json analyze_content({ "keyword": "how to start a blog", "location": "United States" })`

#### get_suggestionsGet autocomplete suggestions and related searches from Google, Bing, and YouTube.

`json get_suggestions({ "keyword": "email marketing", "source": "google" })`


🏢 Business Tools — analyze, find

#### analyze_businessRetrieve business listing data including reviews, ratings, hours, photos, and contact information from Google, Trustpilot, TripAdvisor, and more.

`json analyze_business({ "keyword": "best coffee shop", "location": "New York, United States", "source": "google" })`

#### find_businessesSearch and discover businesses by category, keyword, and geographic location.

`json find_businesses({ "keyword": "plumber", "location": "San Francisco, United States" })`


📱 App Tools — analyze

#### analyze_appGet App Store and Google Play data — ratings, reviews, rankings, category position, and competitor apps.

`json analyze_app({ "appId": "com.example.app", "store": "google_play", "location": "United States" })`


⚙️ Utility Tools — locations, categories, languages, download

#### get_locationsList all available target locations with their location codes for use in other tools.

`json get_locations({ "query": "united" })`

#### get_categoriesBrowse available business and content categories with their category codes.

`json get_categories({ "query": "marketing" })`

#### get_languagesList all supported languages with their language codes.

`json get_languages({})`

#### download_dataRetrieve a full dataset from a presigned R2 download URL returned by any other tool.

`json download_data({ "url": "https://r2.example.com/data.json?presigned..." })`

---

`$3`

Every tool returns a PreviewResponse — a token-optimized envelope designed for AI consumption:

`json { "summary": "Found 150 keywords for 'seo tools'. Top: 'best seo tools' (12,100 searches/mo, KD 67)", "preview": [ { "keyword": "best seo tools", "volume": 12100, "difficulty": 67, "cpc": 8.50 }, { "keyword": "free seo tools", "volume": 8400, "difficulty": 42, "cpc": 3.20 } ], "stats": { "totalRows": 150, "avgVolume": 2500, "avgDifficulty": 45 }, "downloadUrl": "https://r2.example.com/data.json?presigned...", "appliedFilters": { "sortBy": "volume", "order": "desc", "location": "United States" }, "nextSteps": [ { "description": "Get difficulty deep-dive for top keywords", "toolCall": "analyze_keywords({ keywords: [\"best seo tools\", \"free seo tools\"] })" }, { "description": "Check SERP features for top keyword", "toolCall": "analyze_serp({ keyword: \"best seo tools\" })" } ] }`

| Field | Tokens | Purpose | |-------|--------|---------| |summary| ~50 | One-line actionable insight | |preview| ~200-400 | Top 5-10 representative rows for quick decisions | |stats| ~30 | Dataset-level aggregates | |downloadUrl| ~50 | Presigned R2 URL for the full dataset (all rows) | |appliedFilters| ~30 | What filters/sorting were applied | |nextSteps | ~50 | Suggested follow-up tool calls |

---

`Environment Variables`

| Variable | Required | Default | Description | |----------|----------|---------|-------------| |DATAFORSEO_USERNAME| Yes | — | Your DataForSEO API username | |DATAFORSEO_PASSWORD| Yes | — | Your DataForSEO API password | |R2_ACCOUNT_ID| No | — | Cloudflare R2 account ID (enables full dataset downloads) | |R2_ACCESS_KEY_ID| No | — | R2 access key ID | |R2_SECRET_ACCESS_KEY| No | — | R2 secret access key | |R2_BUCKET| No | — | R2 bucket name for dataset storage | |HEALTH_PORT | No | 8080| Port for health check and metrics HTTP server | |DISABLE_HEALTH_SERVER | No | — | Set to trueto disable the health/metrics HTTP server | |LOG_LEVEL | No | info | Log level: debug, info, warn, error |

> Tip: Without R2 configured, tools still work — you just won't get downloadUrl for full datasets. Previews always work.

---

`Recommended Workflows`

`$3`

Ask your AI to run a complete SEO audit in one conversation:

`1. "Analyze the domain example.com" → analyze_domain → traffic overview, top pages, keyword distribution

2. "How's their backlink profile?" → analyze_backlinks → referring domains, anchor distribution, link quality

3. "Who are their main competitors?" → analyze_competitors → competing domains ranked by keyword overlap

4. "Compare their backlinks with the top competitor" → compare_backlinks → side-by-side link profile comparison

5. "Find keyword gaps between us and the top competitor" → compare_domains → keywords they rank for that you don't`

`$3`

`1. "Find competitors for my domain example.com" → analyze_competitors → list of competing domains

2. "Compare my domain with the top 3 competitors" → compare_domains → traffic, keywords, authority comparison

3. "What keywords does competitor.com rank for that I don't?" → research_keywords({ keywords: ["competitor.com"], dataType: "for_site" })

4. "Analyze the SERP for their top keyword" → analyze_serp → SERP features, ranking positions, content requirements`

`$3`

`1. "Research keywords for 'project management software'" → research_keywords → 200+ keyword ideas with volume and difficulty

2. "Analyze difficulty for the top 10 keywords" → analyze_keywords → difficulty scores, SERP competition, trends

3. "What does the SERP look like for 'best project management tools'?" → analyze_serp → featured snippets, PAA questions, top results

4. "Analyze the content of top-ranking pages for that keyword" → analyze_content → word count, topics covered, readability benchmarks

5. "Get autocomplete suggestions for content angles" → get_suggestions → related queries and long-tail variations`

---

`Development`

`bash

`Clone the repository`


git clone https://github.com/yigitkonur/mcp-marketers.git
cd mcp-marketers
Install dependencies (runs postinstall patches automatically)

npm install
Build TypeScript

npm run build
Run all unit tests (336 tests)

npm test
Run a specific test

npm test -- -t "analyze_backlinks"
Lint

npm run lint
Validate SDK-only boundary (no direct HTTP calls)

npm run validate:sdk-only
Dev mode with auto-reload

npm run dev
Test with MCP Inspector

npx @modelcontextprotocol/inspector \
  -e DATAFORSEO_USERNAME=xxx -e DATAFORSEO_PASSWORD=xxx \
  --cli node build/index.js --method tools/list

$3

`src/ ├── index.ts # Entry point — registers tools + middleware pipeline ├── mcp/ │ ├── tools/ # 19 tool handlers (research-keywords, analyze-*, etc.) │ ├── middleware/ # compose → errorBoundary → rateLimit → timeout → circuitBreaker │ ├── response/ # ResponseBuilder (preview, stats, nextSteps) │ └── client/ # DataForSEO SDK wrapper (all API calls go through here) ├── services/ # Business logic layer ├── data/ │ ├── dataforseo/ # SDK client initialization │ └── cache/ # In-memory cache with TTL ├── utils/ │ ├── storage/ # R2 client for full dataset uploads/downloads │ └── tokens/ # Token counting and response compression ├── health/ # Health checks and graceful shutdown └── observability/ # Structured logging, metrics, tracing`

---

`Troubleshooting`


DataForSEO credentials not working

- Verify your username and password at app.dataforseo.com - Make sureDATAFORSEO_USERNAME and DATAFORSEO_PASSWORD are set in the envblock of your MCP config - Credentials are the API login/password from the DataForSEO dashboard, not your account email - Check that your DataForSEO account has an active balance — most endpoints cost credits per request


R2 download URLs not working / no downloadUrl in response

- R2 is optional — tools work without it, you just won't get full dataset download URLs - If you want download URLs, set all four R2 environment variables:R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_BUCKET- Make sure your R2 bucket exists and the access key has read/write permissions - Presigned URLs expire after a set period — if a URL stops working, re-run the tool


Token limits / large responses

- Marketers MCP is designed to avoid this — preview responses are 300-500 tokens - If you're seeing large responses, check thattokenBudgetis configured in the tool definition - ThedownloadUrlfield provides access to the full dataset without consuming context window - Usedownload_data tool to retrieve specific datasets when the AI needs full data


Build or install errors

- Requires Node.js 18 or higher: check with node --version- Thepostinstall script patches the DataForSEO SDK — if it fails, run npm run patch:dataforseo-client && npm run patch:sdk-missing-methodsmanually - If TypeScript build fails, ensure you havenpm installcompleted successfully first - Deletenode_modules and package-lock.json then run npm install for a clean start


Tool not found / "Unknown tool" error

- Restart Claude Desktop after modifying claude_desktop_config.json- Verify theargs path in your config points to the built file: /path/to/mcp-marketers/build/index.js- Runnpm run build if you haven't built yet — the build/directory must exist - Test with MCP Inspector to verify tools are loading:npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list


Health server port conflict

- The health server defaults to port 8080 — if that's in use, set HEALTH_PORTto another port - SetDISABLE_HEALTH_SERVER=true` to skip the health server entirely
- The MCP server itself uses stdio transport and does not need a port

---

License

MIT © Yigit Konur

Built with Model Context Protocol and DataForSEO

📈 Marketers MCP 📈

Your AI assistant just became an SEO expert.

Token-optimized SEO tools for AI agents. 19 tools. One MCP server. Zero context window waste.

---

Get Started •
Why Marketers MCP •
Tools •
Configuration •
Examples

---

The Pitch

🔑 Keywords

Seed keywords → goldmine of opportunities. Volume, difficulty, CPC, trends — all in one call.

🔗 Backlinks

Full backlink profile analysis. Referring domains, anchor text, new/lost links, competitor comparisons.

📊 SERP Analysis

SERP features, ranking positions, content analysis. See what Google actually shows users.

🏢 Competitor Intel

Find competitors, compare domains head-to-head, discover gaps in your strategy.

$3

``You: "Find keywords related to 'email marketing' with volume > 1000"

Full dataset (247 rows) available via download URL — AI never chokes on data.`

---

`Why Marketers MCP`

❌ Without Marketers MCP	✅ With Marketers MCP
1. Open SEMrush, Ahrefs, or Moz 2. Run queries, wait for results 3. Export CSVs 4. Copy-paste data into AI chat 5. Hit token limits on large datasets 6. Get fragmented, incomplete analysis 7. Repeat for every follow-up question	1. Ask your AI about any SEO topic 2. AI calls DataForSEO directly via MCP 3. Gets token-optimized preview (300-500 tokens) 4. Downloads full dataset when needed via R2 URL 5. Chains multiple tools for complete workflows 6. One conversation. Full analysis. No tab-switching.

❌ Without Marketers MCP

✅ With Marketers MCP

---

`Get Started`

`$3`

> Note: This package is not yet published to npm. You must clone and build locally.

`bash git clone https://github.com/yigitkonur/mcp-marketers.git cd mcp-marketers npm install npm run build`

`$3`

Sign up at dataforseo.com and grab your API login and password from the dashboard.

`$3`

Add this to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json

Restart Claude Desktop after saving the config.

`$3`

`bash claude mcp add seo \ -e DATAFORSEO_USERNAME=your_username \ -e DATAFORSEO_PASSWORD=your_password \ -- node /absolute/path/to/mcp-marketers/build/index.js`

`$3`

Add to your .cursor/mcp.json or Windsurf MCP config:

---

`Transport Modes`

Marketers MCP supports three transport modes:

`$3`

A remote MCP endpoint is deployed and ready to use:

`https://mcp-marketers.seodoold.workers.dev/mcp`

Connect from any MCP client that supports HTTP Streamable transport:

`json { "mcpServers": { "marketers-remote": { "type": "streamable-http", "url": "https://mcp-marketers.seodoold.workers.dev/mcp" } } }`

`$3`

`bash

`Start on default port 3001`


MCP_TRANSPORT=http npx mcp-marketers
Custom port

MCP_TRANSPORT=http MCP_PORT=8080 npx mcp-marketers

`json { "mcpServers": { "marketers-http": { "type": "streamable-http", "url": "http://localhost:3001/mcp" } } }`

---

`Tool Reference`

`$3`

---


🔑 Keywords Tools — research, analyze, compare

#### research_keywordsDiscover keyword ideas from seed keywords using multiple discovery methods. Supports Google, Bing, and Clickstream data sources.

`json research_keywords({ "keywords": ["seo tools"], "dataType": "suggestions", "minVolume": 1000, "location": "United States" })`

#### analyze_keywordsGet detailed keyword metrics including difficulty scores, search volume, CPC, competition, and historical trends.

`json analyze_keywords({ "keywords": ["email marketing", "content marketing"], "location": "United States" })`

#### compare_keywordsCompare keywords side-by-side on volume, difficulty, CPC, and trend data for prioritization.

`json compare_keywords({ "keywords": ["react vs vue", "angular vs svelte"], "location": "United States" })`


🌐 Domains Tools — analyze, competitors, compare

#### analyze_domainFull domain SEO overview including organic traffic estimates, top ranking pages, keyword distribution, and technology stack.

`json analyze_domain({ "domain": "example.com", "location": "United States" })`

#### analyze_competitorsDiscover which domains compete with yours for the same organic keywords and traffic.

`json analyze_competitors({ "domain": "example.com", "location": "United States" })`

#### compare_domainsHead-to-head comparison of 2-5 domains on traffic, keyword overlap, backlink strength, and domain authority.

`json compare_domains({ "domains": ["site-a.com", "site-b.com", "site-c.com"], "location": "United States" })`


🔗 Backlinks Tools — analyze, compare, monitor

#### analyze_backlinksComprehensive backlink profile analysis — referring domains, anchor text distribution, dofollow/nofollow ratio, link types.

`json analyze_backlinks({ "target": "example.com", "sortBy": "rank", "limit": 100 })`

#### compare_backlinksCompare backlink profiles between two or more domains to find link-building opportunities.

`json compare_backlinks({ "targets": ["site-a.com", "site-b.com"] })`

#### monitor_backlinksTrack newly acquired and recently lost backlinks for any domain.

`json monitor_backlinks({ "target": "example.com", "mode": "new" })`


📊 SERP & Content Tools — serp, content, suggestions

#### analyze_serpAnalyze SERP features for a keyword — featured snippets, People Also Ask, local packs, knowledge panels, and organic rankings.

`json analyze_serp({ "keyword": "best crm software", "location": "United States" })`

#### analyze_contentContent analysis for target keywords — typical word count, readability scores, topic coverage among top-ranking pages.

`json analyze_content({ "keyword": "how to start a blog", "location": "United States" })`

#### get_suggestionsGet autocomplete suggestions and related searches from Google, Bing, and YouTube.

`json get_suggestions({ "keyword": "email marketing", "source": "google" })`


🏢 Business Tools — analyze, find

#### analyze_businessRetrieve business listing data including reviews, ratings, hours, photos, and contact information from Google, Trustpilot, TripAdvisor, and more.

`json analyze_business({ "keyword": "best coffee shop", "location": "New York, United States", "source": "google" })`

#### find_businessesSearch and discover businesses by category, keyword, and geographic location.

`json find_businesses({ "keyword": "plumber", "location": "San Francisco, United States" })`


📱 App Tools — analyze

#### analyze_appGet App Store and Google Play data — ratings, reviews, rankings, category position, and competitor apps.

`json analyze_app({ "appId": "com.example.app", "store": "google_play", "location": "United States" })`


⚙️ Utility Tools — locations, categories, languages, download

#### get_locationsList all available target locations with their location codes for use in other tools.

`json get_locations({ "query": "united" })`

#### get_categoriesBrowse available business and content categories with their category codes.

`json get_categories({ "query": "marketing" })`

#### get_languagesList all supported languages with their language codes.

`json get_languages({})`

#### download_dataRetrieve a full dataset from a presigned R2 download URL returned by any other tool.

`json download_data({ "url": "https://r2.example.com/data.json?presigned..." })`

---

`$3`

Every tool returns a PreviewResponse — a token-optimized envelope designed for AI consumption:

---

`Environment Variables`

> Tip: Without R2 configured, tools still work — you just won't get downloadUrl for full datasets. Previews always work.

---

`Recommended Workflows`

`$3`

Ask your AI to run a complete SEO audit in one conversation:

`1. "Analyze the domain example.com" → analyze_domain → traffic overview, top pages, keyword distribution

2. "How's their backlink profile?" → analyze_backlinks → referring domains, anchor distribution, link quality

3. "Who are their main competitors?" → analyze_competitors → competing domains ranked by keyword overlap

4. "Compare their backlinks with the top competitor" → compare_backlinks → side-by-side link profile comparison

5. "Find keyword gaps between us and the top competitor" → compare_domains → keywords they rank for that you don't`

`$3`

`1. "Find competitors for my domain example.com" → analyze_competitors → list of competing domains

2. "Compare my domain with the top 3 competitors" → compare_domains → traffic, keywords, authority comparison

3. "What keywords does competitor.com rank for that I don't?" → research_keywords({ keywords: ["competitor.com"], dataType: "for_site" })

4. "Analyze the SERP for their top keyword" → analyze_serp → SERP features, ranking positions, content requirements`

`$3`

`1. "Research keywords for 'project management software'" → research_keywords → 200+ keyword ideas with volume and difficulty

2. "Analyze difficulty for the top 10 keywords" → analyze_keywords → difficulty scores, SERP competition, trends

3. "What does the SERP look like for 'best project management tools'?" → analyze_serp → featured snippets, PAA questions, top results

4. "Analyze the content of top-ranking pages for that keyword" → analyze_content → word count, topics covered, readability benchmarks

5. "Get autocomplete suggestions for content angles" → get_suggestions → related queries and long-tail variations`

---

`Development`

`bash

`Clone the repository`


git clone https://github.com/yigitkonur/mcp-marketers.git
cd mcp-marketers
Install dependencies (runs postinstall patches automatically)

npm install
Build TypeScript

npm run build
Run all unit tests (336 tests)

npm test
Run a specific test

npm test -- -t "analyze_backlinks"
Lint

npm run lint
Validate SDK-only boundary (no direct HTTP calls)

npm run validate:sdk-only
Dev mode with auto-reload

npm run dev
Test with MCP Inspector

npx @modelcontextprotocol/inspector \
  -e DATAFORSEO_USERNAME=xxx -e DATAFORSEO_PASSWORD=xxx \
  --cli node build/index.js --method tools/list

$3

---

`Troubleshooting`


DataForSEO credentials not working


R2 download URLs not working / no downloadUrl in response


Token limits / large responses


Build or install errors


Tool not found / "Unknown tool" error


Health server port conflict

---

License

Built with Model Context Protocol and DataForSEO