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
Source
View on GitHubThis 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.
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.
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')"Source
View on GitHubfrom 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)
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)
{
"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
{
"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 guideACP 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 Allowlist
{
"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"
]
}
}
]
}
}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.