Semrush MCP Server

Instructions

Implementation Reference

• src/index.ts:268-277 (handler)

  The handler function for the 'domain_organic_search' tool. It validates input using the schema, then calls the Semrush API with the 'domain_organic' report type and specified parameters to retrieve organic search keywords for the given domain.
  case 'domain_organic_search': { const { domain, database, limit, offset } = DomainOrganicSearchSchema.parse(args); data = await callSemrushAPI('domain_organic', { domain, database, display_limit: limit, display_offset: offset, export_columns: 'Ph,Po,Nq,Cp,Ur,Tr,Tc,Co,Nr,Td', }); break;
• src/index.ts:72-77 (schema)

  Zod schema defining the input parameters for the domain_organic_search tool, including domain, database, limit, and offset.
  const DomainOrganicSearchSchema = z.object({ domain: z.string().describe('Domain to analyze'), database: z.string().default('us').describe('Database code'), limit: z.coerce.number().default(10).describe('Number of results'), offset: z.coerce.number().default(0).describe('Offset for pagination'), });
• src/index.ts:193-200 (registration)

  Registration of the 'domain_organic_search' tool in the ListTools response, including name, description, and input schema reference.
  name: 'domain_organic_search', description: 'Get organic search keywords for a domain', inputSchema: { type: 'object', properties: DomainOrganicSearchSchema.shape, required: ['domain'], }, },
• src/index.ts:103-155 (helper)

  Shared helper function that performs API calls to Semrush, handles both standard and analytics/v1 endpoints, parses CSV responses using parseCSV, and manages errors.
  async function callSemrushAPI(reportType: string, params: Record<string, any>, isAnalyticsV1: boolean = false) { try { let requestUrl: string; let queryParams: Record<string, any>; if (isAnalyticsV1) { requestUrl = `${SEMRUSH_API_BASE}/analytics/v1/`; // Note the trailing slash for consistency queryParams = { key: API_KEY, type: reportType, // e.g., 'backlinks_overview' ...params, }; } else { requestUrl = SEMRUSH_API_BASE + '/'; // Main API endpoint: https://api.semrush.com/ queryParams = { key: API_KEY, type: reportType, // e.g., 'domain_ranks' ...params, }; } console.error(`Calling Semrush API. URL: ${requestUrl}, Params: ${JSON.stringify(queryParams)}`); const response = await axios.get(requestUrl, { params: queryParams, }); if (typeof response.data === 'string') { const parsed = parseCSV(response.data); // If CSV parsing itself returns an error object, or if it's an array but empty (parsed from only headers or error string) if (parsed && typeof parsed === 'object' && ('error' in parsed || (Array.isArray(parsed) && 'headers' in parsed && parsed.length === 0))) { return parsed; // Return the error object or {error: ..., headers:..., data: []} } return parsed; // Otherwise, return the array of parsed objects or results from parseCSV } return response.data; // If not a string, return as is (might be JSON error from API) } catch (error: any) { console.error(`Semrush API call failed for type/path ${reportType}. Error: ${error.message}`); if (error.response) { console.error('Semrush API Error Response Status:', error.response.status); console.error('Semrush API Error Response Data:', error.response.data); let errorMessage = error.response.data; if (typeof errorMessage === 'string') { const semrushErrorMatch = errorMessage.match(/ERROR :: (.+)/); if (semrushErrorMatch && semrushErrorMatch[1]) { errorMessage = semrushErrorMatch[1]; } } throw new Error(`Semrush API error (${error.response.status}): ${errorMessage || error.response.statusText}`); } throw new Error(`Semrush API request failed: ${error.message}`); } }
• src/index.ts:25-59 (helper)

  Helper function to parse semicolon-delimited CSV data returned by Semrush API into an array of objects or error object.
  function parseCSV(csvData: string): Record<string, any>[] | { error: string } { if (!csvData || typeof csvData !== 'string') { return { error: 'Invalid or empty CSV data' }; } try { const lines = csvData.trim().split('\n').filter(line => line.trim().length > 0); if (lines.length === 0) { return { error: 'CSV data is empty after trimming' }; } if (lines.length === 1 && lines[0].startsWith('ERROR ::')) { return { error: lines[0] }; } if (lines.length <= 1 && !lines[0].includes(';')) { // Likely not a valid CSV if only one line and no delimiter return { error: 'No data rows found or invalid CSV header' }; } const headers = lines[0].split(';'); const dataRows = lines.slice(1); if (dataRows.length === 0 && lines.length === 1) { // Only header row means no data // Return headers so client knows what fields were expected, but indicate no data return { error: 'No data results, only headers returned' }; } const results = dataRows.map(line => { const values = line.split(';'); const row: Record<string, string> = {}; headers.forEach((header, index) => { row[header.trim()] = values[index]?.trim() || ''; }); return row; }); return results; } catch (error: any) { console.error('Error parsing CSV:', error.message); return { error: 'Failed to parse CSV data' }; } }