Skip to documentation
AgentSEO / Docs
Browse documentation
View Markdown ↗

SDKs & Libraries

Accelerate your development with our official libraries and agent-ready integrations. Geo-targeted endpoints accept deterministic location_code inputs, and async jobs can be polled via getJob().

Want the packaging by runtime instead of by library? Browse the integration guides for n8n, Make, Claude Code, and OpenClaw.

Node.js SDK

Fully typed SDK for Node.js (ESM). Best for backend services, workers, Next.js apps, and programmatic SEO pipelines.

Current first-class methods include localAudit, contentGap, search, analyzeSerp, aiOverviewExtract, localVisibilityTrack, llmMentionsTrack, contentDecayDetect, keywordClusterBuild, getJob. For endpoints not yet wrapped, call the REST API directly.

Installation

npm install @agentseo/sdk@0.1.1

This plain JavaScript example works with published SDK 0.1.1. It submits once, keeps the job ID, and polls with getJob using a 90-second polling budget and a 10-second request timeout. If polling stops, resume the printed job ID; do not resubmit.

Code example
import { AgentSEO } from "@agentseo/sdk";

const apiKey = process.env.AGENTSEO_API_KEY;
if (!apiKey) throw new Error("Set AGENTSEO_API_KEY");
const client = new AgentSEO({ apiKey, timeoutMs: 10_000 });
const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));

async function pollExistingJob(jobId) {
  const deadline = Date.now() + 90_000;
  while (Date.now() < deadline) {
    const status = await client.getJob(jobId);
    if (status.status === "completed") {
      if (status.result == null) throw new Error("Completed job has no result");
      return status;
    }
    if (status.status === "failed") {
      throw new Error(status.error?.message || "Job failed");
    }
    if (!["queued", "pending", "processing", "retrying"].includes(status.status)) {
      throw new Error("Unexpected job status: " + status.status);
    }
    await sleep(Math.min(2_000, Math.max(0, deadline - Date.now())));
  }
  throw new Error("Polling deadline reached. Resume job " + jobId + "; do not resubmit.");
}

// Submit once. Polling does not submit another billable request.
const job = await client.analyzeSerp({
  "keyword": "seo agency austin",
  "location": "Austin, TX",
  "location_code": 1026201
});
if (typeof job.jobId !== "string" || !job.jobId) throw new Error("Missing job ID");
console.error("Job:", job.jobId);
const status = await pollExistingJob(job.jobId);
console.log(JSON.stringify(status.result, null, 2));

Python SDK

Official Python client for data science and backend workflows.

The Python SDK mirrors the same core workflow set as the Node SDK and adds get_job plus wait_for_job for async handling.

Installation

Use an activated Python 3.9+ virtual environment and install from the official source repository. The import check makes no API requests. For a setup without an SDK, use the REST quickstart.

Code example
git clone https://github.com/AgentSEO-dev/agentseo-clients.git
cd agentseo-clients
python -m pip install ./packages/python-sdk
python -c "from agentseo_sdk import AgentSEOClient; print('AgentSEOClient import OK')"
Code example
from agentseo_sdk import AgentSEOClient

client = AgentSEOClient(
    api_key="sk_live_...",
    project_id="client-alpha",
    workflow_id="nightly-refresh",
)

job = client.content_gap(
    url="https://example.com/blog/post",
    keyword="seo agency austin",
    location="Austin, TX",
    location_code=1026201,
)

status = client.wait_for_job(
    job["jobId"],
    timeout_seconds=90,
)

if status["status"] == "failed":
    raise RuntimeError(status["error"]["message"])

print(status["result"])

MCP Server

Model Context Protocol server for Claude Desktop and Cursor. Use the hosted endpoint when you want zero local install, or keep the local package when you want the MCP process on your own machine.

For runtime-specific guidance, see the Claude Code integration page or the Claude Desktop integration page.

Hosted MCP (Claude Code)

Code example
claude mcp add --transport http agentseo https://www.agentseo.dev/mcp \
  --header "Authorization: Bearer sk_live_..." \
  --header "x-project-id: client-alpha" \
  --header "x-workflow-id: nightly-refresh"

Hosted MCP (Cursor)

Code example
{
  "mcpServers": {
    "agentseo": {
      "url": "https://www.agentseo.dev/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_...",
        "x-project-id": "client-alpha",
        "x-workflow-id": "nightly-refresh"
      }
    }
  }
}

Local MCP package

Code example
{
  "mcpServers": {
    "agentseo": {
      "command": "npx",
      "args": ["-y", "@agentseo/mcp-server"],
      "env": {
        "AGENTSEO_API_KEY": "sk_live_...",
        "AGENTSEO_API_URL": "https://www.agentseo.dev/api/v1",
        "AGENTSEO_PROJECT_ID": "client-alpha",
        "AGENTSEO_WORKFLOW_ID": "nightly-refresh"
      }
    }
  }
}

Hosted and local MCP both require a server-side API key with no allowed domains. A browser-restricted key will also be rejected by the local MCP package.

Read full MCP setup guide

ACP Adapter

For OpenClaw, prefer the first-party AgentSEO plugin. Use the ACP adapter when you need to import AgentSEO tools into a custom ACP-compatible runtime.

This package is published by AgentSEO. The docs do not claim upstream OpenClaw-maintainer approval. See the OpenClaw integration page for positioning and setup guidance.

OpenClaw Plugin

openclaw plugins install @agentseo/openclaw-plugin --pin

OpenClaw Allowlist

Code example
{
  "agents": {
    "list": [
      {
        "id": "seo",
        "tools": {
          "allow": [
            "agentseo_local_audit",
            "agentseo_content_gap",
            "agentseo_ai_overview_extract",
            "agentseo_local_visibility_track",
            "agentseo_rank_track",
            "agentseo_job_status"
          ]
        }
      }
    ]
  }
}
Read the OpenClaw integration guide

Need full endpoint coverage?

Use the API reference for routes not yet wrapped by the official SDK methods, or call the REST API directly from your runtime.

API Reference