{"id":28180709,"url":"https://github.com/dataforseo/mcp-server-typescript","last_synced_at":"2025-05-16T03:11:00.117Z","repository":{"id":291952681,"uuid":"963874629","full_name":"dataforseo/mcp-server-typescript","owner":"dataforseo","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-14T14:23:33.000Z","size":90,"stargazers_count":25,"open_issues_count":0,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-14T15:38:32.997Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dataforseo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-10T10:47:08.000Z","updated_at":"2025-05-14T14:23:37.000Z","dependencies_parsed_at":"2025-05-07T11:49:09.051Z","dependency_job_id":null,"html_url":"https://github.com/dataforseo/mcp-server-typescript","commit_stats":null,"previous_names":["dataforseo/mcp-server-typescript"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dataforseo%2Fmcp-server-typescript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dataforseo%2Fmcp-server-typescript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dataforseo%2Fmcp-server-typescript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dataforseo%2Fmcp-server-typescript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dataforseo","download_url":"https://codeload.github.com/dataforseo/mcp-server-typescript/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254459118,"owners_count":22074606,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-16T03:10:58.719Z","updated_at":"2025-05-16T03:11:00.087Z","avatar_url":"https://github.com/dataforseo.png","language":"TypeScript","funding_links":[],"categories":["📚 Projects (2474 total)"],"sub_categories":["MCP Servers"],"readme":"# DataForSEO MCP Server\n\nModel Context Protocol (MCP) server implementation for DataForSEO, enabling Claude to interact with selected DataForSEO APIs and obtain SEO data through a standardized interface. \n\n## Features\n\n- SERP API: real-time Search Engine Results Page (SERP) data for Google, Bing, and Yahoo;\n- KEYWORDS_DATA API: keyword research and clickstream data, including search volume, cost-per-click, and other metrics;   \n- ONPAGE API: allows crawling websites and webpages according to customizable parameters to obtain on-page SEO performance metrics; \n- DATAFORSEO_LABS API: data on keywords, SERPs, and domains based on DataForSEO's in-house databases and proprietary algorithms.\n\n## Prerequisites\n\n- Node.js (v14 or higher)\n- DataForSEO API credentials (API login and password)\n\n## Installation\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/dataforseo/mcp-server-typescript\ncd mcp-server-typescript\n```\n\n2. Install dependencies:\n```bash\nnpm install\n```\n\n3. Set up environment variables:\n```bash\n# Required\nexport DATAFORSEO_USERNAME=your_username\nexport DATAFORSEO_PASSWORD=your_password\n\n# Optional: specify which modules to enable (comma-separated)\n# If not set, all modules will be enabled\nexport ENABLED_MODULES=\"SERP,KEYWORDS_DATA,ONPAGE,DATAFORSEO_LABS,BACKLINKS,BUSINESS_DATA,DOMAIN_ANALYTICS\"\n\n# Optional: enable full API responses\n# If not set or set to false, the server will filter and transform API responses to a more concise format\n# If set to true, the server will return the full, unmodified API responses\nexport DATAFORSEO_FULL_RESPONSE=\"false\"\n```\n\n## Installation as an NPM Package\n\nYou can install the package globally:\n\n```bash\nnpm install -g dataforseo-mcp-server\n```\n\nOr run it directly without installation:\n\n```bash\nnpx dataforseo-mcp-server\n```\n\nRemember to set environment variables before running the command:\n\n```bash\n# Required environment variables\nexport DATAFORSEO_USERNAME=your_username\nexport DATAFORSEO_PASSWORD=your_password\n\n# Run with npx\nnpx dataforseo-mcp-server\n```\n\n## Building and Running\n\nBuild the project:\n```bash\nnpm run build\n```\n\nRun the server:\n```bash\nnpm start\n```\n\n## Available Modules\n\nThe following modules are available to be enabled/disabled:\n\n- `SERP`: real-time SERP data for Google, Bing, and Yahoo;\n- `KEYWORDS_DATA`: keyword research and clickstream data;\n- `ONPAGE`: crawl websites and webpages to obtain on-page SEO performance metrics;\n- `DATAFORSEO_LABS`: data on keywords, SERPs, and domains based on DataForSEO's databases and algorithms;\n- `BACKLINKS`: data on inbound links, referring domains and referring pages for any domain, subdomain, or webpage;\n- `BUSINESS_DATA`: based on business reviews and business information publicly shared on the following platforms: Google, Trustpilot, Tripadvisor;\n- `DOMAIN_ANALYTICS`: helps identify all possible technologies used for building websites and offers Whois data;\n\n## Adding New Tools/Modules\n\n### Module Structure\n\nEach module corresponds to a specific DataForSEO API:\n- `SERP` module → [SERP API](https://docs.dataforseo.com/v3/serp/overview)\n- `KEYWORDS_DATA` module → [Keywords Data API](https://docs.dataforseo.com/v3/keywords_data/overview)\n- `ONPAGE` module → [OnPage API](https://docs.dataforseo.com/v3/on_page/overview)\n- `DATAFORSEO_LABS` module → [DataForSEO Labs API](https://docs.dataforseo.com/v3/dataforseo_labs/overview)\n- `BACKLINKS`: module → [Backlinks API](https://docs.dataforseo.com/v3/backlinks/overview)\n- `BUSINESS_DATA`: module → [Business Data API](https://docs.dataforseo.com/v3/business_data/overview)\n- `DOMAIN_ANALYTICS`: module → [Domain Analytics API](https://docs.dataforseo.com/v3/domain_analytics/overview)\n\n### Implementation Options\n\nYou can either:\n1. Add a new tool to an existing module\n2. Create a completely new module\n\n### Adding a New Tool\n\nHere's how to add a new tool to any new or pre-existing module:\n\n```typescript\n// src/modules/your-module/tools/your-tool.tool.ts\nimport { BaseTool } from '../../base.tool';\nimport { DataForSEOClient } from '../../../client/dataforseo.client';\nimport { z } from 'zod';\n\nexport class YourTool extends BaseTool {\n  constructor(private client: DataForSEOClient) {\n    super(client);\n    // DataForSEO API returns extensive data with many fields, which can be overwhelming\n    // for AI agents to process. We select only the most relevant fields to ensure\n    // efficient and focused responses.\n    this.fields = [\n      'title',           // Example: Include the title field\n      'description',     // Example: Include the description field\n      'url',            // Example: Include the URL field\n      // Add more fields as needed\n    ];\n  }\n\n  getName() {\n    return 'your-tool-name';\n  }\n\n  getDescription() {\n    return 'Description of what your tool does';\n  }\n\n  getParams(): z.ZodRawShape {\n    return {\n      // Required parameters\n      keyword: z.string().describe('The keyword to search for'),\n      location: z.string().describe('Location in format \"City,Region,Country\" or just \"Country\"'),\n      \n      // Optional parameters\n      fields: z.array(z.string()).optional().describe('Specific fields to return in the response. If not specified, all fields will be returned'),\n      language: z.string().optional().describe('Language code (e.g., \"en\")'),\n    };\n  }\n\n  async handle(params: any) {\n    try {\n      // Make the API call\n      const response = await this.client.makeRequest({\n        endpoint: '/v3/dataforseo_endpoint_path',\n        method: 'POST',\n        body: [{\n          // Your request parameters\n          keyword: params.keyword,\n          location: params.location,\n          language: params.language,\n        }],\n      });\n\n      // Validate the response for errors\n      this.validateResponse(response);\n\n      //if the main data array is specified in tasks[0].result[:] field\n      const result = this.handleDirectResult(response);\n      //if main data array specified in tasks[0].result[0].items field\n      const result = this.handleItemsResult(response);\n      // Format and return the response\n      return this.formatResponse(result);\n    } catch (error) {\n      // Handle and format any errors\n      return this.formatErrorResponse(error);\n    }\n  }\n}\n```\n\n### Creating a New Module\n\n1. Create a new directory under `src/modules/` for your module:\n```bash\nmkdir -p src/modules/your-module-name\n```\n\n2. Create module files:\n```typescript\n// src/modules/your-module-name/your-module-name.module.ts\nimport { BaseModule } from '../base.module';\nimport { DataForSEOClient } from '../../client/dataforseo.client';\nimport { YourTool } from './tools/your-tool.tool';\n\nexport class YourModuleNameModule extends BaseModule {\n  constructor(private client: DataForSEOClient) {\n    super();\n  }\n\n  getTools() {\n    return {\n      'your-tool-name': new YourTool(this.client),\n    };\n  }\n}\n```\n\n3. Register your module in `src/config/modules.config.ts`:\n```typescript\nexport const AVAILABLE_MODULES = [\n  'SERP',\n  'KEYWORDS_DATA',\n  'ONPAGE',\n  'DATAFORSEO_LABS',\n  'YOUR_MODULE_NAME'  // Add your module name here\n] as const;\n```\n\n4. Initialize your module in `src/index.ts`:\n```typescript\nif (isModuleEnabled('YOUR_MODULE_NAME', enabledModules)) {\n  modules.push(new YourModuleNameModule(dataForSEOClient));\n}\n```\n\n## What endpoints/APIs do you want us to support next?\n\nWe're always looking to expand the capabilities of this MCP server. If you have specific DataForSEO endpoints or APIs you'd like to see supported, please:\n\n1. Check the [DataForSEO API Documentation](https://docs.dataforseo.com/v3/) to see what's available\n2. Open an issue in our GitHub repository with:\n   - The API/endpoint you'd like to see supported;\n   - A brief description of your use case;\n   - Describe any specific features you'd like to see implemented.\n\nYour feedback helps us prioritize which APIs to support next!\n\n## Resources\n\n- [Model Context Protocol Documentation](https://modelcontextprotocol.io/quickstart)\n- [DataForSEO API Documentation](https://docs.dataforseo.com/)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdataforseo%2Fmcp-server-typescript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdataforseo%2Fmcp-server-typescript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdataforseo%2Fmcp-server-typescript/lists"}