SIGN UPLOG IN
X (Twitter)LinkedInGitHubDiscordYouTube

How to integrate Semrush MCP with LlamaIndex

Connect LlamaIndex to Semrush MCP. Show top anchor texts for example.com, compare backlink profiles for three domains, and more using natural language, with authentication handled for you.

Get started for freeGet a demo
Semrush logoSemrush
Api Key

Semrush is a leading SEO tool suite for keyword research, competitor analysis, and campaign tracking. It empowers marketers to improve search rankings and optimize online visibility.

74 Tools

Introduction

This guide walks you through connecting Semrush to LlamaIndex using the Composio tool router. By the end, you'll have a working Semrush agent that can research organic and paid keywords, analyze backlinks, compare competitor domains, track local map rankings, and manage business listings through natural language commands.

This guide will help you understand how to give your LlamaIndex agent real control over a Semrush account through Composio's Semrush MCP server.

Before we dive in, let's take a quick look at the key ideas and tools involved.

Also integrate Semrush with

Claude CodeCursorChatGPTClaude CoworkAntigravityOpenAI Agents SDKClaude Agent SDKMuseCodexKimi CodeGrok BuildVS CodeOpenCodeOpenClawHermesAtomic AgentCLIGoogle ADKLangChainVercel AI SDKMastra AICrewAIPydantic AIAutoGen

TL;DR

Here's what you'll learn:
  • Set your OpenAI and Composio API keys
  • Install LlamaIndex and Composio packages
  • Create a Composio Tool Router session for Semrush
  • Connect LlamaIndex to the Semrush MCP server
  • Build a Semrush-powered agent using LlamaIndex
  • Interact with Semrush through natural language

What is LlamaIndex?

LlamaIndex is a data framework for building LLM applications. It provides tools for connecting LLMs to external data sources and services through agents and tools.

Key features include:

  • ReAct Agent: Reasoning and acting pattern for tool-using agents
  • MCP Tools: Native support for Model Context Protocol
  • Context Management: Maintain conversation context across interactions
  • Async Support: Built for async/await patterns

What is the Semrush MCP server, and what's possible with it?

The Semrush MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Semrush account. It provides structured and secure access to keyword, search competitor, backlink, and advertising data, so your agent can research keywords, compare domains, inspect backlink profiles, analyze search competitors, and review paid campaigns on your behalf.

  • Keyword research and content planning: Have your agent find related, broad match, and question-based keywords, then review search volume, cost per click, competition, and keyword difficulty.
  • Organic search analysis: Let the agent examine a domain's ranking keywords, top organic pages, ranking subdomains, and search results across supported regional databases.
  • Competitor and keyword gap research: Direct your agent to identify organic or paid search competitors and compare up to five domains for shared, unique, and missing keywords.
  • Backlink profile assessment: Instruct your agent to review backlinks, referring domains, anchor text, indexed pages, authority score distribution, historical trends, and geographic or top-level domain diversity.
  • Paid search and shopping research: Have your agent inspect paid keywords, search ads, advertising history, Product Listing Ad keywords and copies, and competing advertisers.

What is the Composio tool router, and how does it fit here?

What is Composio SDK?

Composio's Composio SDK helps agents find the right tools for a task at runtime. You can plug in multiple toolkits (like Gmail, HubSpot, and GitHub), and the agent will identify the relevant app and action to complete multi-step workflows. This can reduce token usage and improve the reliability of tool calls. Read more here: Getting started with Composio SDK

The tool router generates a secure MCP URL that your agents can access to perform actions.

How the Composio SDK works

The Composio SDK follows a three-phase workflow:

  1. Discovery: Searches for tools matching your task and returns relevant toolkits with their details.
  2. Authentication: Checks for active connections. If missing, creates an auth config and returns a connection URL via Auth Link.
  3. Execution: Executes the action using the authenticated connection.

Step-by-step Guide

Step by step10 STEPS
1

Prerequisites

Before you begin, make sure you have:
  • Python 3.8/Node 16 or higher installed
  • A Composio account with the API key
  • An OpenAI API key
  • A Semrush account and project
  • Basic familiarity with async Python/Typescript
2

Getting API Keys for OpenAI, Composio, and Semrush

OpenAI API key (OPENAI_API_KEY)
  • Go to the OpenAI dashboard
  • Create an API key if you don't have one
  • Assign it to OPENAI_API_KEY in .env
Composio API key and user ID
  • Log into the Composio dashboard
  • Copy your API key from Settings
    • Use this as COMPOSIO_API_KEY
  • Pick a stable user identifier (email or ID)
    • Use this as COMPOSIO_USER_ID
3

Installing dependencies

npm install @composio/llamaindex @llamaindex/openai @llamaindex/tools @llamaindex/workflow dotenv

Create a new Typescript project and install the necessary dependencies:

  • @composio/llamaindex: Composio's LlamaIndex integration
  • @llamaindex/openai: OpenAI LLM integration
  • @llamaindex/tools: MCP client for LlamaIndex
  • @llamaindex/workflow: Workflow framework for LlamaIndex
  • dotenv: Environment variable management
4

Set environment variables

bash
OPENAI_API_KEY=your-openai-api-key
COMPOSIO_API_KEY=your-composio-api-key
COMPOSIO_USER_ID=your-user-id

Create a .env file in your project root:

These credentials will be used to:

  • Authenticate with OpenAI's GPT-5 model
  • Connect to Composio's Tool Router
  • Identify your Composio user session for Semrush access
5

Import modules

import "dotenv/config";
import readline from "node:readline/promises";
import { stdin as input, stdout as output } from "node:process";

import { Composio } from "@composio/core";

import { mcp } from "@llamaindex/tools";
import { agent as createAgent } from "@llamaindex/workflow";
import { openai } from "@llamaindex/openai";

dotenv.config();

Create a new file called semrush_llamaindex_agent.ts and import the required modules:

Key imports:

  • dotenv.config loads .env at runtime
  • readline gives us a simple CLI chat loop
  • Composio is the main Composio SDK client
  • mcp connects to an MCP endpoint
  • createAgent builds a LlamaIndex agent
  • openai configures the LLM backend
6

Load environment variables and initialize Composio

const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
const COMPOSIO_API_KEY = process.env.COMPOSIO_API_KEY;
const COMPOSIO_USER_ID = process.env.COMPOSIO_USER_ID;

if (!OPENAI_API_KEY) throw new Error("OPENAI_API_KEY is not set");
if (!COMPOSIO_API_KEY) throw new Error("COMPOSIO_API_KEY is not set");
if (!COMPOSIO_USER_ID) throw new Error("COMPOSIO_USER_ID is not set");

What's happening:

This ensures missing credentials cause early, clear errors before the agent attempts to initialise.

7

Create a Tool Router session and build the agent function

async function buildAgent() {

  console.log(`Initializing Composio client...${COMPOSIO_USER_ID!}...`);
  console.log(`COMPOSIO_USER_ID: ${COMPOSIO_USER_ID!}...`);

  const composio = new Composio({
    apiKey: COMPOSIO_API_KEY,
    provider: new LlamaindexProvider(),
  });

  const session = await composio.create(
    COMPOSIO_USER_ID!,
    {
      toolkits: ["semrush"],
    },
  );

  const mcpUrl = session.mcp.url;
  console.log(`Composio Tool Router MCP URL: ${mcpUrl}`);

  const server = mcp({
    url: mcpUrl,
    clientName: "composio_tool_router_with_llamaindex",
    requestInit: {
      headers: {
        "x-api-key": COMPOSIO_API_KEY!,
      },
    },
    // verbose: true,
  });

  const tools = await server.tools();

  const llm = openai({ apiKey: OPENAI_API_KEY, model: "gpt-5" });

  const agent = createAgent({
    name: "composio_tool_router_with_llamaindex",
        description : "An agent that uses Composio Tool Router MCP tools to perform actions.",
    systemPrompt:
      "You are a helpful assistant connected to Composio Tool Router."+
"Use the available tools to answer user queries and perform Semrush actions." ,
    llm,
    tools,
  });

  return agent;
}

What's happening here:

  • We create a Composio client using your API key and configure it with the LlamaIndex provider
  • We then create a tool router MCP session for your user, specifying the toolkits we want to use (in this case, semrush)
  • The session returns an MCP HTTP endpoint URL that acts as a gateway to all your configured tools
  • LlamaIndex will connect to this endpoint to dynamically discover and use the available Semrush tools.
  • The MCP tools are mapped to LlamaIndex-compatible tools and plug them into the Agent.
8

Create an interactive chat loop

async function chatLoop(agent: ReturnType<typeof createAgent>) {
  const rl = readline.createInterface({ input, output });

  console.log("Type 'quit' or 'exit' to stop.");

  while (true) {
    let userInput: string;

    try {
      userInput = (await rl.question("\nYou: ")).trim();
    } catch {
      console.log("\nAgent: Bye!");
      break;
    }

    if (!userInput) {
      continue;
    }

    const lower = userInput.toLowerCase();
    if (lower === "quit" || lower === "exit") {
      console.log("Agent: Bye!");
      break;
    }

    try {
      process.stdout.write("Agent: ");

      const stream = agent.runStream(userInput);
      let finalResult: any = null;

      for await (const event of stream) {
        // The event.data contains the streamed content
        const data: any = event.data;

        // Check for streaming delta content
        if (data?.delta) {
          process.stdout.write(data.delta);
        }

        // Store final result for fallback
        if (data?.result || data?.message) {
          finalResult = data;
        }
      }

      // If no streaming happened, show the final result
      if (finalResult) {
        const answer =
          finalResult.result ??
          finalResult.message?.content ??
          finalResult.message ??
          "";
        if (answer && typeof answer === "string" && !answer.includes("[object")) {
          process.stdout.write(answer);
        }
      }

      console.log(); // New line after streaming completes
    } catch (err: any) {
      console.error("\nAgent error:", err?.message ?? err);
    }
  }

  rl.close();
}

What's happening:

  • We're creating a direct terminal interface to chat with Semrush
  • The LLM's responses are streamed to the CLI for faster interaction.
  • The agent uses context to maintain conversation history
  • The agent processes the request, selects appropriate Semrush tools, and returns a result
  • We extract the answer from the result data structure and display it to the user
  • You can type 'quit' or 'exit' to stop the chat loop gracefully
  • Agent responses and any errors are streamed in a clear, readable format
9

Define the main entry point

async function main() {
  try {
    const agent = await buildAgent();
    await chatLoop(agent);
  } catch (err) {
    console.error("Failed to start agent:", err);
    process.exit(1);
  }
}

main();

What's happening here:

  • We're orchestrating the entire application flow
  • The agent gets built with proper error handling
  • Then we kick off the interactive chat loop so you can start talking to Semrush
10

Run the agent

npx ts-node llamaindex-agent.ts

When prompted, authenticate and authorise your agent with Semrush, then start asking questions.

Complete Code

Here's the complete code to get you started with Semrush and LlamaIndex:

import "dotenv/config";
import readline from "node:readline/promises";
import { stdin as input, stdout as output } from "node:process";

import { Composio } from "@composio/core";
import { LlamaindexProvider } from "@composio/llamaindex";

import { mcp } from "@llamaindex/tools";
import { agent as createAgent } from "@llamaindex/workflow";
import { openai } from "@llamaindex/openai";

dotenv.config();

const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
const COMPOSIO_API_KEY = process.env.COMPOSIO_API_KEY;
const COMPOSIO_USER_ID = process.env.COMPOSIO_USER_ID;

if (!OPENAI_API_KEY) {
    throw new Error("OPENAI_API_KEY is not set in the environment");
  }
if (!COMPOSIO_API_KEY) {
    throw new Error("COMPOSIO_API_KEY is not set in the environment");
  }
if (!COMPOSIO_USER_ID) {
    throw new Error("COMPOSIO_USER_ID is not set in the environment");
  }

async function buildAgent() {

  console.log(`Initializing Composio client...${COMPOSIO_USER_ID!}...`);
  console.log(`COMPOSIO_USER_ID: ${COMPOSIO_USER_ID!}...`);

  const composio = new Composio({
    apiKey: COMPOSIO_API_KEY,
    provider: new LlamaindexProvider(),
  });

  const session = await composio.create(
    COMPOSIO_USER_ID!,
    {
      toolkits: ["semrush"],
    },
  );

  const mcpUrl = session.mcp.url;
  console.log(`Composio Tool Router MCP URL: ${mcpUrl}`);

  const server = mcp({
    url: mcpUrl,
    clientName: "composio_tool_router_with_llamaindex",
    requestInit: {
      headers: {
        "x-api-key": COMPOSIO_API_KEY!,
      },
    },
    // verbose: true,
  });

  const tools = await server.tools();

  const llm = openai({ apiKey: OPENAI_API_KEY, model: "gpt-5" });

  const agent = createAgent({
    name: "composio_tool_router_with_llamaindex",
    description:
      "An agent that uses Composio Tool Router MCP tools to perform actions.",
    systemPrompt:
      "You are a helpful assistant connected to Composio Tool Router."+
"Use the available tools to answer user queries and perform Semrush actions." ,
    llm,
    tools,
  });

  return agent;
}

async function chatLoop(agent: ReturnType<typeof createAgent>) {
  const rl = readline.createInterface({ input, output });

  console.log("Type 'quit' or 'exit' to stop.");

  while (true) {
    let userInput: string;

    try {
      userInput = (await rl.question("\nYou: ")).trim();
    } catch {
      console.log("\nAgent: Bye!");
      break;
    }

    if (!userInput) {
      continue;
    }

    const lower = userInput.toLowerCase();
    if (lower === "quit" || lower === "exit") {
      console.log("Agent: Bye!");
      break;
    }

    try {
      process.stdout.write("Agent: ");

      const stream = agent.runStream(userInput);
      let finalResult: any = null;

      for await (const event of stream) {
        // The event.data contains the streamed content
        const data: any = event.data;

        // Check for streaming delta content
        if (data?.delta) {
          process.stdout.write(data.delta);
        }

        // Store final result for fallback
        if (data?.result || data?.message) {
          finalResult = data;
        }
      }

      // If no streaming happened, show the final result
      if (finalResult) {
        const answer =
          finalResult.result ??
          finalResult.message?.content ??
          finalResult.message ??
          "";
        if (answer && typeof answer === "string" && !answer.includes("[object")) {
          process.stdout.write(answer);
        }
      }

      console.log(); // New line after streaming completes
    } catch (err: any) {
      console.error("\nAgent error:", err?.message ?? err);
    }
  }

  rl.close();
}

async function main() {
  try {
    const agent = await buildAgent();
    await chatLoop(agent);
  } catch (err: any) {
    console.error("Failed to start agent:", err?.message ?? err);
    process.exit(1);
  }
}

main();

Conclusion

You've successfully connected Semrush to LlamaIndex through Composio's Tool Router MCP layer. Key takeaways:
  • Tool Router dynamically exposes Semrush tools through an MCP endpoint
  • LlamaIndex's ReActAgent handles reasoning and orchestration; Composio handles integrations
  • The agent becomes more capable without increasing prompt size
  • Async Python provides clean, efficient execution of agent workflows
You can easily extend this to other toolkits like Gmail, Notion, Stripe, GitHub, and more by adding them to the toolkits parameter.
TOOLS

Supported Tools

Every Semrush action and event your agent gets out of the box.

Check Semrush account units balance

Fetch remaining Semrush Standard API units for a legacy v3 connection.

Add Semrush review comment

Publish an owner comment to a review that supports replies.

Get ad copies

Retrieves unique ad copies Semrush has observed for a specified domain from a regional database, detailing ads seen in Google's paid search results.

Get competitors in organic search

Use to get a domain's organic search competitors from Semrush as a semicolon-separated string; `display_date` requires 'YYYYMM15' format if used.

Get competitors in paid search

Retrieves a list of a domain's competitors in paid search results from a specified regional database.

Create Semrush GBP post

Create a draft, scheduled, or ready-to-send GBP post.

Create Listing Management location

Create a Semrush Listing Management location.

Create location image

Add a base64-encoded JPEG or PNG image to a Semrush Listing Management location using a read-write v4 key and Local Pro or Business.

Manage Semrush GBP suggestion

Start accepting or rejecting an open GBP suggestion.

Delete Semrush GBP post

Permanently delete a DRAFT, SCHEDULED, or TO_SEND GBP post.

Delete Listing Management location

Permanently delete an eligible location using a read-write v4 key and Local plan.

Delete location image

Permanently delete an image using a read-write v4 key and Local plan.

Delete Semrush review comment

Permanently remove a public review comment.

Disable location listing

Stop distribution for a controllable listing; a parent may affect child listings.

Get domain ad history

Retrieves a domain's 12-month advertising history from Semrush (keywords bid on, ad positions, ad copy) for PPC strategy and competitor analysis; most effective when the domain has ad history in the selected database.

Get domain organic pages

Fetches a report on a domain's unique organic pages ranking in Google's top 100 search results, with options for specifying database, date, columns, sorting, and filtering.

Get domain organic search keywords

Retrieves an organic search keyword report for a domain from a selected Semrush regional database.

Get domain organic subdomains

Retrieves a report on subdomains of a given domain that rank in Google's top 100 organic search results for a specified regional database.

Get domain paid search keywords

Fetches keywords driving paid search traffic to a specified, existing domain using a supported Semrush regional database.

Get PLA search keywords for a domain

Retrieves Product Listing Ad (PLA) search keywords for a specified domain from a Semrush regional database.

Compare domains

Analyzes keyword rankings by comparing up to five domains to find common, unique, or gap keywords, using specified organic/paid types and comparison logic in the `domains` string.

Enable location listing

Resume distribution for a controllable disconnected listing.

Get Semrush GBP metrics

Return GBP metrics for up to five locations.

Get Listing Management location

Get one Listing Management location using a v4 key and Local Pro or Business.

Get Semrush review auto-reply config

Return review auto-reply settings for a location.

Get Semrush review overview

Return review counts, rating distribution, and reply statistics.

List Semrush GBP additional-hour types

Return additional business-hour types available for a GBP location.

List Semrush GBP attributes

Return GBP attributes and allowed values for a category and country.

List Semrush GBP categories

Return GBP categories supported in a country.

List Semrush GBP posts

Return filtered GBP posts for one or more Semrush locations.

List Semrush GBP suggestions

Return GBP data-change suggestions for one or more active locations.

List Listing Management locations

List locations using a v4 key and Local Pro or Business; uses no API units.

List location categories

List Semrush Local business categories supported for a country.

List location images

List location images using a v4 key and Local Pro or Business.

List location listings

Get directory listings using a v4 key and Local Pro or Business.

List location payment options

Get payment options using a v4 key and Local Pro or Business.

List Semrush location reviews

Return a filtered, paginated list of reviews for a Semrush location.

Collect Map Rank Tracker campaign data (consumes credits)

Start a data-collection mutation that creates a new campaign report.

Create Map Rank Tracker campaign

Create persistent Map Rank Tracker campaign data.

Delete Map Rank Tracker campaign

Permanently delete a campaign and all its collected data.

Get Map Rank Tracker campaign

Get one Map Rank Tracker campaign without consuming API units.

Get Map Rank Tracker heatmap

Get a campaign heatmap for one keyword and report timestamp.

Get Map Rank Tracker keyword statuses

Get campaign keyword statuses for the latest or a specified report.

Get Map Rank Tracker metrics

Get average-position and share-of-voice history for one keyword.

Get Map Rank Tracker user limits

Get campaign-slot and monthly Map Rank Tracker credit limits.

List Map Rank Tracker campaigns

List and filter Map Rank Tracker campaigns without consuming API units.

List Map Rank Tracker top competitors

Get a paginated competitor ranking for one keyword and report.

Update Map Rank Tracker campaign

Mutate selected settings of an existing Map Rank Tracker campaign.

Get PLA competitors

Retrieves domains competing with a specified domain in Google's Product Listing Ads (PLA) from a given Semrush regional database.

Get PLA copies

Fetches Product Listing Ad (PLA) copies that Semrush observed for a domain in Google's paid search results.

Update Semrush GBP post

Update a DRAFT, SCHEDULED, or TO_SEND GBP post.

Update Listing Management location

Patch selected fields on a Semrush Listing Management location.

Update location image

Replace a location image caption using a read-write v4 key and Local Pro or Business.

Replace Semrush review auto-reply config

Replace all review auto-reply settings for a location.

Update Semrush review comment

Replace the public text of an editable review comment.

List v4 backlink anchors

List v4 backlink anchors for a URL or domain.

Get v4 authority score profile

Get the v4 referring-domain authority-score distribution.

List v4 backlink competitors

List v4 backlink competitors based on referring-domain overlap.

List v4 backlinks

List v4 backlinks with field selection, filtering, sorting, and pagination.

Compare v4 backlink summaries

Compare v4 backlink summaries for up to ten targets.

Get v4 backlinks historical summary

Get monthly v4 backlink history for a URL or domain.

Get v4 backlinks matrix

Compare shared referring domains and backlinks for up to six targets.

Get v4 backlinks overview

Get aggregated v4 backlink metrics for a URL or domain.

Create v4 project

Create a Semrush v4 project for a domain.

Delete v4 project

Permanently delete a Semrush v4 project and all associated data.

Get v4 project

Get the full details of one accessible Semrush v4 project.

List v4 indexed pages

List v4 indexed backlink pages for a URL or domain.

Get v4 keyword metrics

Get Semrush v4 SEO and PPC metrics for one keyword and country.

List v4 projects

List Semrush v4 projects by ownership or sharing scope.

List v4 referring domains

List v4 referring domains for a URL or domain.

List v4 referring IPs

List v4 referring IP addresses for a URL or domain.

Update v4 project

Rename a Semrush v4 project.

Validate Listing Management location creation

Validate a Listing Management location payload without creating it or consuming a Local Pro location limit.

Validate Listing Management location update

Validate selected changes to a Listing Management location without applying them.

FRAMEWORKS

How to build Semrush MCP Agent with another framework

Claude Code logo

Claude Code

Use Semrush MCP with Claude Code

Cursor logo

Cursor

Use Semrush MCP with Cursor

ChatGPT logo

ChatGPT

Use Semrush MCP with ChatGPT

Claude Cowork logo

Claude Cowork

Use Semrush MCP with Claude Cowork

Antigravity logo

Antigravity

Use Semrush MCP with Antigravity

OpenAI Agents SDK logo

OpenAI Agents SDK

Use Semrush MCP with OpenAI Agents SDK

Claude Agent SDK logo

Claude Agent SDK

Use Semrush MCP with Claude Agent SDK

Muse logo

Muse

Use Semrush MCP with Muse

Codex logo

Codex

Use Semrush MCP with Codex

Kimi Code logo

Kimi Code

Use Semrush MCP with Kimi Code

Grok Build logo

Grok Build

Use Semrush MCP with Grok Build

VS Code logo

VS Code

Use Semrush MCP with VS Code

OpenCode logo

OpenCode

Use Semrush MCP with OpenCode

OpenClaw logo

OpenClaw

Use Semrush MCP with OpenClaw

Hermes logo

Hermes

Use Semrush MCP with Hermes

Atomic Agent logo

Atomic Agent

Use Semrush MCP with Atomic Agent

CLI logo

CLI

Use Semrush MCP with CLI

Google ADK logo

Google ADK

Use Semrush MCP with Google ADK

LangChain logo

LangChain

Use Semrush MCP with LangChain

Vercel AI SDK logo

Vercel AI SDK

Use Semrush MCP with Vercel AI SDK

Mastra AI logo

Mastra AI

Use Semrush MCP with Mastra AI

CrewAI logo

CrewAI

Use Semrush MCP with CrewAI

Pydantic AI logo

Pydantic AI

Use Semrush MCP with Pydantic AI

AutoGen logo

AutoGen

Use Semrush MCP with AutoGen

FAQ

Frequently asked questions

With a standalone Semrush MCP server, the agents and LLMs can only access a fixed set of Semrush tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from Semrush and many other apps based on the task at hand, all through a single MCP endpoint.

Yes, you can. LlamaIndex fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right Semrush tools.

Yes, absolutely. You can configure which Semrush scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do.

All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your Semrush data and credentials are handled as safely as possible.

Start with Semrush.It takes 30 seconds.

Managed auth, hosted MCP servers, and every Semrush tool your agent needs.Free to start.

Start building