Allows AI agents to browse DataForSEO API documentation and execute authenticated API requests for SEO and SERP data.
Also known as dataforseo/mcp-server-typescript, @iflow-mcp/dataforseo-mcp-server, dataforseo-mcp-server
- Stars
- 262
- Tools
- 79
- Downloads, 30 days
- 82
- Latest version
- —
- Last commit
- Nov 2, 2026
- License
- Apache-2.0
What is DataForSEO MCP?
DataForSEO allows AI agents to browse DataForSEO API documentation and execute authenticated API requests for SEO and SERP data. It exposes 79 tools, such as ai_opt_kw_data_loc_and_lang, ai_optimization_keyword_data_search_volume, ai_optimization_llm_models.
Summary generated from the project's README
About DataForSEO MCP server
Fetching SEO and SERP data directly through an AI agent is what this server enables. It provides a bridge for LLMs to interact with the DataForSEO API by allowing them to browse technical documentation and execute authenticated requests for live search engine results or backlink data. Developers can use this via a local stdio connection, a streamable HTTP transport on port 3000, or a remote hosted URL.
To use the server, you must provide credentials via DATAFORSEO_LOGIN and DATAFORSEO_PASSWORD environment variables, though OAuth 2.0 is supported for HTTP mode. The server includes specific tools like docs_search for retrieving documentation with code examples and api_request for making live calls. It also features a field configuration system to trim large JSON payloads, such as Lighthouse data, to only the specific fields your agent needs to process.
What you can do with it
- 1Browse API documentationAn agent can search through the DataForSEO documentation to find specific endpoint details or code examples.
- 2Execute live SEO requestsA developer can task an AI with retrieving real-time SERP data using authenticated API calls.
- 3Filter large API responsesYou can instruct the agent to only return specific data fields to prevent overwhelming the context window.
Written from the project's README. Every use case is checked against a quote from it.
How to install DataForSEO MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall DataForSEO MCP in Claude Code
$ claude mcp add mcp-server-typescript -- npx -y @iflow-mcp/dataforseo-mcp-serverInstall DataForSEO MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-server-typescript": {
"command": "npx",
"args": [
"-y",
"@iflow-mcp/dataforseo-mcp-server"
]
}
}
}Install DataForSEO MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-server-typescript": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@iflow-mcp/dataforseo-mcp-server"
]
}
}
}Install DataForSEO MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-server-typescript","type":"stdio","command":"npx","args":["-y","@iflow-mcp/dataforseo-mcp-server"]}'Install DataForSEO MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-server-typescript": {
"command": "npx",
"args": [
"-y",
"@iflow-mcp/dataforseo-mcp-server"
]
}
}
}Install DataForSEO MCP in Codex
$ codex mcp add mcp-server-typescript -- npx -y @iflow-mcp/dataforseo-mcp-serverInstall DataForSEO MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-server-typescript] command = "npx" args = ["-y", "@iflow-mcp/dataforseo-mcp-server"]
Install DataForSEO MCP in Gemini CLI
$ gemini mcp add -s user mcp-server-typescript npx -- -y @iflow-mcp/dataforseo-mcp-serverInstall DataForSEO MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-server-typescript": {
"command": "npx",
"args": [
"-y",
"@iflow-mcp/dataforseo-mcp-server"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @iflow-mcp/dataforseo-mcp-server 2.8.7 in an isolated container with no network and no keys. It answered and listed 79 tools.
DataForSEO MCP tools 79
Read from the server with tools/listai_opt_kw_data_loc_and_langUtility tool for 'AI Optimization Keyword Data Locations and Languages' (ai_opt_kw_data_loc_and_lang) to get list of availible locations and languages
ai_optimization_keyword_data_search_volumeThis endpoint provides search volume data for your target keywords, reflecting their estimated usage in AI LLMs
ai_optimization_llm_modelsUtility tool for ai_optimization_llm_response to get list of availible locations and languages
ai_optimization_llm_responseThis endpoint allows you to retrieve structured responses from a specific AI model, based on the input parameters
ai_optimization_llm_mentions_filtersThis endpoint provides all the necessary information about filters that can be used with AI Optimization LLM Mentions API endpoints
ai_opt_llm_ment_loc_and_langUtility tool for 'AI Optimization LLM Mentions Locations and Languages' (ai_opt_llm_ment_loc_and_lang) to get list of available locations and languages
ai_opt_llm_ment_searchThis endpoint provides aggregated LLM mentions metrics grouped by the most frequently mentioned pages for the specified target
ai_opt_llm_ment_agg_metricsThis endpoint provides aggregated metrics for mentions of the keywords or domains specified in the target array of the request.
ai_opt_llm_ment_cross_agg_metricsThis endpoint provides aggregated metrics grouped by custom keys for mentions of the keywords or domains specified in the target array of the request
ai_opt_llm_ment_top_domainsThis endpoint provides aggregated LLM mentions metrics grouped by the most frequently mentioned domains for the specified target
ai_opt_llm_ment_top_pagesThis endpoint provides aggregated LLM mentions metrics grouped by the most frequently mentioned pages for the specified target
ai_optimization_chat_gpt_scraperThis endpoint provides results from ChatGPT searches
Show all 79 toolsShow fewer tools
ai_optimization_chat_gpt_scraper_locationsUtility tool for ai_optimization_chat_gpt_scraper to get list of available locations
serp_organic_live_advancedGet organic search results for a keyword in specified search engine
serp_locationsUtility tool for serp_organic_live_advanced to get list of availible locations.
serp_youtube_locationsUtility tool to get list of available locations for: serp_youtube_organic_live_advanced, serp_youtube_video_info_live_advanced, serp_youtube_video_comments_live_advanced, serp_youtube_video_subtitles_live_advanced.
serp_youtube_organic_live_advancedprovides top 20 blocks of youtube search engine results for a keyword
serp_youtube_video_info_live_advancedprovides data on the video you specify
serp_youtube_video_comments_live_advancedprovides data on the video comments you specify
serp_youtube_video_subtitles_live_advancedprovides data on the video subtitles you specify
kw_data_google_ads_locationsUtility tool for kw_data_google_ads_search_volume to get list of availible locations.
kw_data_google_ads_search_volumeGet search volume data for keywords from Google Ads
kw_data_dfs_trends_demographyThis endpoint will provide you with the demographic breakdown (by age and gender) of keyword popularity per each specified term based on DataForSEO Trends data
kw_data_dfs_trends_subregion_interestsThis endpoint will provide you with location-specific keyword popularity data from DataForSEO Trends
kw_data_dfs_trends_exploreThis endpoint will provide you with the keyword popularity data from DataForSEO Trends. You can check keyword trends for Google Search, Google News, and Google Shopping
kw_data_google_trends_categoriesThis endpoint will provide you list of Google Trends Categories
kw_data_google_trends_exploreThis endpoint will provide you with the keyword popularity data from the ‘Explore’ feature of Google Trends. You can check keyword trends for Google Search, Google News, Google Images, Google Shopping, and YouTube
on_page_content_parsingThis endpoint allows parsing the content on any page you specify and will return the structured content of the target page, including link URLs, anchors, headings, and textual content.
on_page_instant_pagesUsing this function you will get page-specific data with detailed information on how well a particular page is optimized for organic search
on_page_lighthouseThe OnPage Lighthouse API is based on Google’s open-source Lighthouse project for measuring the quality of web pages and web apps.
dataforseo_labs_google_ranked_keywordsThis endpoint will provide you with the list of keywords that any domain or webpage is ranking for. You will also get SERP elements related to the keyword position, as well as impressions, monthly searches and other data relevant to the returned keywords.
dataforseo_labs_google_competitors_domainThis endpoint will provide you with a full overview of ranking and traffic data of the competitor domains from organic and paid search. In addition to that, you will get the metrics specific to the keywords both competitor domains and your domain rank for within the same SERP.
dataforseo_labs_google_domain_rank_overviewThis endpoint will provide you with ranking and traffic data from organic and paid search for the specified domain. You will be able to review the domain ranking distribution in SERPs as well as estimated monthly traffic volume for both organic and paid results.
dataforseo_labs_google_keyword_ideasThe Keyword Ideas provides search terms that are relevant to the product or service categories of the specified keywords. The algorithm selects the keywords which fall into the same categories as the seed keywords specified in a POST array. As a result, you will get a list of relevant keyword ideas for up to 200 seed keywords. Along with each keyword idea, you will get its search volume rate for the last month, search volume trend for the previous 12 months, as well as current cost-per-click and competition values. Moreover, this endpoint supplies minimum, maximum and average values of daily impressions, clicks and CPC for each result.
dataforseo_labs_google_related_keywordsThe Related Keywords endpoint provides keywords appearing in the "searches related to" SERP element You can get up to 4680 keyword ideas by specifying the search depth. Each related keyword comes with the list of relevant product categories, search volume rate for the last month, search volume trend for the previous 12 months, as well as current cost-per-click and competition values. Moreover, this endpoint supplies minimum, maximum and average values of daily impressions, clicks and CPC for each result. Datasource: DataForSEO SERPs Database Search algorithm: depth-first search for queries appearing in the "search related to" element of SERP for the specified seed keyword.
dataforseo_labs_google_keyword_suggestionsThe Keyword Suggestions provides search queries that include the specified seed keyword. The algorithm is based on the full-text search for the specified keyword and therefore returns only those search terms that contain the keyword you set in the POST array with additional words before, after, or within the specified key phrase. Returned keyword suggestions can contain the words from the specified key phrase in a sequence different from the one you specify. As a result, you will get a list of long-tail keywords with each keyword in the list matching the specified search term. Along with each suggested keyword, you will get its search volume rate for the last month, search volume trend for the previous 12 months, as well as current cost-per-click and competition values. Moreover, this endpoint supplies minimum, maximum and average values of daily impressions, clicks and CPC for each result.
dataforseo_labs_google_historical_serpThis endpoint will provide you with Google SERPs collected within the specified time frame. You will also receive a complete overview of featured snippets and other extra elements that were present within the specified dates. The data will allow you to analyze the dynamics of keyword rankings over time for the specified keyword and location.
dataforseo_labs_google_serp_competitorsThis endpoint will provide you with a list of domains ranking for the keywords you specify. You will also get SERP rankings, rating, estimated traffic volume, and visibility values the provided domains gain from the specified keywords.
dataforseo_labs_bulk_keyword_difficultyThis endpoint will provide you with the Keyword Difficulty metric for a maximum of 1,000 keywords in one API request. Keyword Difficulty stands for the relative difficulty of ranking in the first top-10 organic results for the related keyword. Keyword Difficulty in DataForSEO API responses indicates the chance of getting in top-10 organic results for a keyword on a logarithmic scale from 0 to 100.
dataforseo_labs_google_subdomainsThis endpoint will provide you with a list of subdomains of the specified domain, along with the ranking distribution across organic and paid search. In addition to that, you will also get the estimated traffic volume of subdomains based on search volume.
dataforseo_labs_google_keyword_overviewThis endpoint provides Google keyword data for specified keywords. For each keyword, you will receive current cost-per-click, competition values for paid search, search volume, search intent, monthly searches
dataforseo_labs_google_top_searchesThe Top Searches endpoint of DataForSEO Labs API can provide you with over 7 billion keywords from the DataForSEO Keyword Database. Each keyword in the API response is provided with a set of relevant keyword data with Google Ads metrics
dataforseo_labs_search_intentThis endpoint will provide you with search intent data for up to 1,000 keywords. For each keyword that you specify when setting a task, the API will return the keyword's search intent and intent probability. Besides the highest probable search intent, the results will also provide you with other likely search intent(s) and their probability. Based on keyword data and search results data, our system has been trained to detect four types of search intent: informational, navigational, commercial, transactional.
dataforseo_labs_google_keywords_for_siteThe Keywords For Site endpoint will provide you with a list of keywords relevant to the target domain. Each keyword is supplied with relevant, search volume data for the last month, cost-per-click, competition
dataforseo_labs_google_domain_intersectionThis endpoint will provide you with the keywords for which both specified domains rank within the same SERP. You will get search volume, competition, cost-per-click and impressions data on each intersecting keyword. Along with that, you will get data on the first and second domain's SERP element discovered for this keyword, as well as the estimated traffic volume and cost of ad traffic.
dataforseo_labs_google_historical_rank_overviewThis endpoint will provide you with historical data on rankings and traffic of the specified domain, such as domain ranking distribution in SERPs and estimated monthly traffic volume for both organic and paid results
dataforseo_labs_google_page_intersectionThis endpoint will provide you with the keywords for which specified pages rank within the same SERP. You will get search volume, competition, cost-per-click and impressions data on each intersecting keyword. Along with that, you will get data on SERP elements that specified pages rank for in search results, as well as the estimated traffic volume and cost of ad traffic. Page Intersection endpoint supports organic, paid, local pack and featured snippet results. Find keywords several webpages rank for: If you would like to get the keywords several pages rank for, you need to specify webpages only in the pages object. This way, you will receive intersected ranked keywords for the specified URLs. Find keywords your competitors rank for but you do not: If you would like to receive all keywords several pages rank for, but particular pages do not, you need to use the exclude_pages array as well. This way you will receive the keywords for which the URLs from the pages object rank for, but the URLs from the exclude_pages array do not
dataforseo_labs_bulk_traffic_estimationThis endpoint will provide you with estimated monthly traffic volumes for up to 1,000 domains, subdomains, or webpages. Along with organic search traffic estimations, you will also get separate values for paid search, featured snippet, and local pack results.
dataforseo_labs_available_filtersHere you will find all the necessary information about filters that can be used with DataForSEO Labs API endpoints. Please, keep in mind that filters are associated with a certain object in the result array, and should be specified accordingly.
dataforseo_labs_google_historical_keyword_dataThis endpoint provides Google historical keyword data for specified keywords, including search volume, cost-per-click, competition values for paid search, monthly searches, and search volume trends. You can get historical keyword data since August, 2021, depending on keywords along with location and language combination
dataforseo_labs_google_relevant_pagesThis endpoint will provide you with rankings and traffic data for the web pages of the specified domain. You will be able to review each page’s ranking distribution and estimated monthly traffic volume from both organic and paid searches.
backlinks_backlinksThis endpoint will provide you with a list of backlinks and relevant data for the specified domain, subdomain, or webpage
backlinks_anchorsThis endpoint will provide you with a detailed overview of anchors used when linking to the specified website with relevant backlink data for each of them
backlinks_bulk_backlinksThis endpoint will provide you with the number of backlinks pointing to domains, subdomains, and pages specified in the targets array. The returned numbers correspond to all live backlinks, that is, total number of referring links with all attributes (e.g., nofollow, noreferrer, ugc, sponsored etc) that were found during the latest check. Note that if you indicate a domain as a target, you will get results for the root domain (domain with all of its subdomains), e.g. dataforseo.com and app.dataforseo.com
backlinks_bulk_new_lost_referring_domainsThis endpoint will provide you with the number of referring domains pointing to the domains, subdomains and pages specified in the targets array. Note that if you indicate a domain as a target, you will get result for the root domain (domain with all of its subdomains), e.g. dataforseo.com and app.dataforseo.com
backlinks_bulk_new_lost_backlinksThis endpoint will provide you with the number of referring domains pointing to domains, subdomains, and pages specified in the targets array. The returned numbers are based on all live referring domains, that is, total number of domains pointing to the target with any type of backlinks (e.g., nofollow, noreferrer, ugc, sponsored etc) that were found during the latest check. Note that if you indicate a domain as a target, you will get result for the root domain (domain with all of its subdomains), e.g. dataforseo.com and app.dataforseo.com
backlinks_bulk_ranksThis endpoint will provide you with rank scores of the domains, subdomains, and pages specified in the targets array. The score is based on the number of referring domains pointing to the specified domains, subdomains, or pages. The rank values represent real-time data for the date of the request and range from 0 (no backlinks detected) to 1,000 (highest rank). A similar scoring system is used in Google’s Page Rank algorithm
backlinks_bulk_referring_domainsThis endpoint will provide you with the number of referring domains pointing to domains, subdomains, and pages specified in the targets array. The returned numbers are based on all live referring domains, that is, total number of domains pointing to the target with any type of backlinks (e.g., nofollow, noreferrer, ugc, sponsored etc) that were found during the latest check. Note that if you indicate a domain as a target, you will get result for the root domain (domain with all of its subdomains), e.g. dataforseo.com and app.dataforseo.com
backlinks_bulk_spam_scoreThis endpoint will provide you with spam scores of the domains, subdomains, and pages you specified in the targets array. Spam Score is DataForSEO’s proprietary metric that indicates how “spammy” your target is on a scale from 0 to 100
backlinks_competitorsThis endpoint will provide you with a list of competitors that share some part of the backlink profile with a target website, along with a number of backlink intersections and the rank of every competing website
backlinks_domain_intersectionThis endpoint will provide you with the list of domains pointing to the specified websites. This endpoint is especially useful for creating a Link Gap feature that shows what domains link to your competitors but do not link out to your website
backlinks_domain_pages_summaryThis endpoint will provide you with detailed summary data on all backlinks and related metrics for each page of the target domain or subdomain you specify. If you indicate a single page as a target, you will get comprehensive summary data on all backlinks for that page
backlinks_domain_pagesThis endpoint will provide you with a detailed overview of domain pages with backlink data for each page
backlinks_page_intersectionThis endpoint will provide you with the list of domains pointing to the specified websites. This endpoint is especially useful for creating a Link Gap feature that shows what domains link to your competitors but do not link out to your website
backlinks_referring_domainsThis endpoint will provide you with a detailed overview of referring domains pointing to the target you specify
backlinks_referring_networksThis endpoint will provide you with a detailed overview of referring domains pointing to the target you specify
backlinks_summaryThis endpoint will provide you with an overview of backlinks data available for a given domain, subdomain, or webpage
backlinks_timeseries_new_lost_summaryThis endpoint will provide you with the number of new and lost backlinks and referring domains for the domain specified in the target field. The results will be provided for a period between the two indicated dates, and metrics will be grouped by the time range that you define: day, week, month, or year. Data from this endpoint will be especially helpful for building time-series graphs of new and lost backlinks and referring domains.
backlinks_timeseries_summaryThis endpoint will provide you with an overview of backlink data for the target domain available during a period between the two indicated dates. Backlink metrics will be grouped by the time range that you define: day, week, month, or year. Data from this endpoint will be especially helpful for building time-series graphs of daily, weekly, monthly, and yearly link-building progress
backlinks_bulk_pages_summaryThis endpoint will provide you with a comprehensive overview of backlinks and related data for a bulk of up to 1000 pages, domains, or subdomains. If you indicate a single page as a target, you will get comprehensive summary data on all backlinks for that page.
backlinks_available_filtersHere you will find all the necessary information about filters that can be used with DataForSEO Backlinks API endpoints. Please, keep in mind that filters are associated with a certain object in the result array, and should be specified accordingly.
business_data_business_listings_searchBusiness Listings Search API provides results containing information about business entities listed on Google Maps in the specified categories. You will receive the address, contacts, rating, working hours, and other relevant data
domain_analytics_whois_overviewThis endpoint will provide you with Whois data enriched with backlink stats, and ranking and traffic info from organic and paid search results. Using this endpoint you will be able to get all these data for the domains matching the parameters you specify in the request
domain_analytics_whois_available_filtersHere you will find all the necessary information about filters that can be used with DataForSEO WHOIS API endpoints. Please, keep in mind that filters are associated with a certain object in the result array, and should be specified accordingly.
domain_analytics_technologies_domain_technologiesUsing this endpoint you will get a list of technologies used in a particular domain
domain_analytics_technologies_available_filtersHere you will find all the necessary information about filters that can be used with DataForSEO Technologies API endpoints. Please, keep in mind that filters are associated with a certain object in the result array, and should be specified accordingly.
content_analysis_searchThis endpoint will provide you with detailed citation data available for the target keyword
content_analysis_summaryThis endpoint will provide you with an overview of citation data available for the target keyword
content_analysis_phrase_trendsThis endpoint will provide you with data on all citations of the target keyword for the indicated date range
Configuration
DATAFORSEO_LOGINDATAFORSEO_PASSWORDFIELD_CONFIG_PATH
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachabledataforseo/mcp-server-typescript is public and reachablegithub.com/dataforseo/mcp-server-typescript ↗Pass
- Package names this repository as its source@iflow-mcp/dataforseo-mcp-server, dataforseo-mcp-server name dataforseo/mcp-server-typescript as sourcenpmjs.com/package/@iflow-mcp/dataforseo-mcp-server ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for dataforseo-mcp-servernpmjs.com/package/dataforseo-mcp-server/v/3.1.3#provenance ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-02github.com/dataforseo/mcp-server-typescript ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @iflow-mcp/dataforseo-mcp-server, dataforseo-mcp-serverPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model79 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubDataForSEO MCP Server
This is the new v3 MCP server. The previous v2+ MCP server is deprecated and lives at dataforseo/mcp-server-typescript-deprecated.
MCP server and CLI for LLM agents to browse DataForSEO API documentation and make authenticated API requests. By default the binary starts an MCP server on stdio; CLI commands are an optional second mode.
Quick Start
Start the MCP server on stdio (default mode; set DATAFORSEO_LOGIN / DATAFORSEO_PASSWORD):
npx dataforseo-mcp-server@latest
HTTP transport (port 3000; override with PORT):
npx dataforseo-mcp-server@latest --mode http
Authentication
OAuth 2.0 (default for HTTP MCP): works out of the box. MCP clients discover the DataForSEO authorization server via Protected Resource metadata and send Authorization: Bearer tokens.
Fallback: API login/password via environment variables (HTTP Basic). Required for CLI and stdio MCP; on HTTP it is used when no Authorization header is present.
# bash / macOS / Linux
export DATAFORSEO_LOGIN="your_api_login"
export DATAFORSEO_PASSWORD="your_api_password"
# PowerShell
$env:DATAFORSEO_LOGIN="your_api_login"
$env:DATAFORSEO_PASSWORD="your_api_password"
REM CMD
set DATAFORSEO_LOGIN=your_api_login
set DATAFORSEO_PASSWORD=your_api_password
DATAFORSEO_USERNAME is accepted as an alias for DATAFORSEO_LOGIN. Get API keys at https://app.dataforseo.com/api-access.
MCP Server
The same tool implementations power both the MCP server and the CLI. One binary serves both modes; MCP is the default.
How the binary chooses a mode:
- MCP stdio — default when no CLI command is passed
- MCP HTTP — pass
--mode http(Streamable HTTP on port 3000; override withPORT) - CLI — when the first command is
docsorrequest, or when--cli/--help/--versionis passed
MCP stdio (default):
npx dataforseo-mcp-server
MCP HTTP:
npx dataforseo-mcp-server --mode http
CLI:
npx dataforseo-mcp-server docs index
MCP client config (Cursor, Claude Desktop, and similar clients that use mcpServers):
Via URL — use the hosted remote MCP server, or start a local HTTP server (npx dataforseo-mcp-server --mode http) and point the client at it. OAuth works out of the box; env credentials are optional fallback only.
Public remote MCP server URL: https://mcp.dataforseo.com/v3/mcp
{
"mcpServers": {
"dataforseo": {
"url": "https://mcp.dataforseo.com/v3/mcp"
}
}
}
Local server (default port 3000):
{
"mcpServers": {
"dataforseo": {
"url": "http://localhost:3000/mcp"
}
}
}
Via command (stdio) — the client starts the binary itself (stdio is the default mode). OAuth is not used on this transport — set env credentials (or pass them in the MCP client env block):
{
"mcpServers": {
"dataforseo": {
"command": "npx",
"args": [
"dataforseo-mcp-server",
// Optional additional args:
// "--docs-cache-dir", "D:\\my-docs-cache",
// "--configuration", "field-config.json"
],
"env": {
"DATAFORSEO_LOGIN": "your_api_login",
"DATAFORSEO_PASSWORD": "your_api_password",
// Optional additional env:
// "FIELD_CONFIG_PATH": "field-config.json"
}
}
}
}
From the repo root during development:
{
"mcpServers": {
"dataforseo": {
"command": "npx",
"args": ["tsx", "src/index.ts"],
"cwd": "/path/to/mcp-server-typescript"
}
}
}
MCP Tools
| Tool | Title | Description |
|---|---|---|
docs_index |
Docs Index | Fetch documentation index, optionally filtered by section (24h cache) |
docs_list_sections |
Docs List Sections | Return available documentation section names |
docs_search |
Docs Search | Fetch documentation from a documentation URL (needCodeExample, 24h cache) |
api_request |
API Request | Make an authenticated API request |
api_request uses .ai paths by default. Set noAiMode to true in MCP requests, or pass --no-ai-mode in the CLI, to use the standard path. Request body is passed as data (JSON object or array). The --param option is CLI-only.
HTTP transport
Streamable HTTP endpoints:
POST /mcpPOST /http
OAuth 2.0 Protected Resource metadata (RFC 9728) is always exposed so MCP clients can discover the authorization server and authenticate with Bearer tokens:
GET /.well-known/oauth-protected-resourceGET /.well-known/oauth-protected-resource/mcpGET /.well-known/oauth-protected-resource/http
Behind a reverse proxy, set TRUST_PROXY=true so metadata URLs use https.
Auth priority on HTTP requests:
Authorization: BasicheaderAuthorization: Bearerheader (OAuth access token)- Env credentials (
DATAFORSEO_LOGIN/DATAFORSEO_PASSWORD) — fallback when noAuthorizationheader is sent
CLI (optional)
In addition to MCP, the same binary exposes docs and request as CLI commands.
Commands
| Command | Description |
|---|---|
npx dataforseo-mcp-server docs index |
Fetch full API documentation index |
npx dataforseo-mcp-server docs index --section "SERP API" |
Filter index by API section |
npx dataforseo-mcp-server docs index --list-sections |
List available sections |
npx dataforseo-mcp-server docs search <url> |
Fetch documentation from a documentation URL or path (cURL example only by default) |
npx dataforseo-mcp-server docs search <url> --need-code-example |
Fetch documentation with PHP, Node.js, Python, and C# examples |
npx dataforseo-mcp-server request -X <method> -p <path> |
Make an authenticated API request (.ai path by default) |
From a built local clone you can also use npx . instead of npx dataforseo-mcp-server.
Examples
# Browse SERP API endpoints
npx dataforseo-mcp-server docs index --section "SERP API"
# Read endpoint documentation (path or full docs URL)
npx dataforseo-mcp-server docs search serp/google/organic/live/regular
npx dataforseo-mcp-server docs search https://docs.dataforseo.com/v3/serp/google/organic/live/regular
# Include multi-language code examples (PHP, Node.js, Python, C#)
npx dataforseo-mcp-server docs search backlinks/referring_networks/live --need-code-example
# Live SERP request (recommended: use --param)
npx dataforseo-mcp-server request -X POST -p /v3/serp/google/organic/live/regular \
--param keyword=dataforseo --param language_code=en --param location_code=2840
# Same request via JSON body
npx dataforseo-mcp-server request -X POST -p /v3/serp/google/organic/live/regular \
-d '[{"keyword":"dataforseo","location_code":2840,"language_code":"en"}]'
Documentation responses are cached for 24 hours. Default cache directory:
- Windows:
%LOCALAPPDATA%\dataforseo-mcp-server\docs-cache - macOS:
~/Library/Caches/dataforseo-mcp-server/docs-cache - Linux:
~/.cache/dataforseo-mcp-server/docs-cache(or$XDG_CACHE_HOME)
Override with --cache-dir <path> on CLI docs commands. For MCP, pass --docs-cache-dir <path> in server startup args.
API responses are returned as the response body only (parsed JSON when possible). When a field configuration is loaded, api_request / request responses are trimmed to the configured fields for that endpoint path (see Field configuration).
Field configuration
Optionally limit which fields are returned from API responses. Unlike the previous multi-tool MCP server (keys = tool names), this package keys the config by API endpoint path.
# MCP stdio (default when no CLI command is passed)
npx dataforseo-mcp-server --configuration field-config.json
# MCP HTTP
npx dataforseo-mcp-server --mode http --configuration field-config.json
# CLI
npx dataforseo-mcp-server --configuration field-config.json request -X POST -p /v3/backlinks/summary/live --param target=example.com
Or set env:
FIELD_CONFIG_PATH— path to a JSON file (Node)FIELD_CONFIG_JSON— inline JSON string (Node / Cloudflare Worker)
Minimal example (see field-config.example.json for a fuller sample):
{
"supported_fields": {
"/v3/serp/google/organic/live/advanced": ["id", "items.title", "items.url", "status_code"],
"/v3/backlinks/summary/live": ["id", "items.backlinks", "items.referring_domains", "status_code"]
}
}
Behavior:
- Built-in defaults always apply for
/v3/on_page/lighthouse/live/json(shrunk Lighthouse payload). Custom config merges on top and can override any path. - Path match ignores
.aisuffix, trailing slash, and host (full URLs work). - If the path is configured with a non-empty field list → only those fields are kept (applied to each
tasks[].result[]item). - If the path has an empty field list
[]→ full response for that path (disables filtering). - If the path is missing from both defaults and custom config → full response.
Copy the example and trim to the endpoints you use:
cp field-config.example.json my-config.json
Architecture
src/
├── index.ts # Unified entry (MCP by default stdio; CLI if docs/request/--cli)
├── config/ # URLs, sections, auth server
├── core/
│ ├── api/ # auth, client, path, request-body
│ ├── cli/ # program, error, output
│ ├── config/ # field configuration + defaults
│ ├── docs/ # path, section, cache
│ ├── http/ # fetch
│ ├── mcp/ # startup args (--configuration, --docs-cache-dir)
│ ├── tools/ # shared CLI + MCP tool implementations
│ ├── utils/ # field filter
│ ├── env.ts
│ └── version.ts
├── mcp/
│ ├── init-mcp-server.ts
│ ├── tool-definition.ts
│ ├── auth-middleware.ts
│ ├── http-routes.ts
│ ├── index.ts # stdio transport
│ └── index-http.ts # streamable HTTP
└── worker/ # Cloudflare Worker entry (built separately)
Build outputs
| Target | Command | Output | Used by |
|---|---|---|---|
| Node (MCP + CLI) | npm run build (tsc) |
dist/index.js |
bin, Docker, start* scripts |
| Cloudflare Worker | npm run worker:build |
build/worker/worker/index-worker.js |
wrangler.jsonc → main |
Worker path is build/worker/worker/... because tsconfig.worker.json sets rootDir to src and the entry lives at src/worker/index-worker.ts.
For LLM Agents
Read SKILL.md in this repo for full agent instructions.
Development
Requires Node.js 20+.
npm install
npm run build
# Dev (tsx, no build step)
npm run dev # MCP stdio (default)
npm run dev:mcp:http # MCP HTTP
npm run dev -- docs index --section "SERP API" # CLI
# After build
npm run start # MCP stdio (default)
npm run start:mcp:http # Streamable HTTP
npx . docs index --list-sections
DataForSEO MCP questions
How do I add DataForSEO MCP to Claude Code?
Run claude mcp add mcp-server-typescript -- npx -y @iflow-mcp/dataforseo-mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add DataForSEO MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does DataForSEO MCP provide?
It exposes 79 tools, including ai_opt_kw_data_loc_and_lang, ai_optimization_keyword_data_search_volume, ai_optimization_llm_models, ai_optimization_llm_response, ai_optimization_llm_mentions_filters.