Bisibility

@bisibility/mcp

Part of bisibility - an open-source SEO platform for keyword research, backlink analysis, and Google rank tracking. This repository contains the MCP server that exposes bisibility tools to AI agents.

Docs · API reference · Roadmap

Status: Developer preview.

Distribution

Distribution status and release channels

Model Context Protocol server for the bisibility REST API. It exposes stdio tools backed by the published @bisibility/sdk package.

Requirements

• Node.js 18 or newer
• A bisibility API key
• A bisibility API v1 base URL

Install

Run the published stdio server without a global install:

npx -y @bisibility/mcp

For local development, install and build from this package directory:

From this package directory:

npm install
npm run build

The SDK is consumed from the npm registry:

"@bisibility/sdk": "^0.17.1"

MCPB bundle

Directories and clients that support MCPB can distribute bisibility as a one-click local bundle. The bundle includes the stdio server and all production dependencies, but never a bisibility credential. The client collects configuration during installation.

Build the upload artifact with:

npm ci
npm run build
npm run build:mcpb

The versioned file is written to artifacts/.

Environment

export BISIBILITY_API_KEY="bsb_pat_live_..."
export BISIBILITY_BASE_URL="https://eu.bisibility.com/api/v1"
export BISIBILITY_PROJECT_ID="prj_..."
export BISIBILITY_MCP_READ_ONLY="1"
export BISIBILITY_MCP_TOOLSETS="projects,keywords,checks,rank-history"

BISIBILITY_BASE_URL is optional and defaults to https://eu.bisibility.com/api/v1. For self-hosted installs, set it to your API v1 root, for example https://rank.example.com/api/v1. BISIBILITY_API_KEY accepts a project key (bsb_key_live_...) or personal access token (bsb_pat_live_...). Set optional BISIBILITY_PROJECT_ID as the default X-Bisibility-Project selector for project-implicit PAT tools; a tool's optional project_id argument overrides it for that call. Every resource ID accepted by the MCP server, including BISIBILITY_PROJECT_ID, must use the current typed public ID format: a canonical lowercase prefix plus _ and a 24-character lowercase suffix, for example prj_a1b2c3d4e5f6g7h8j9k0m2n3. Malformed IDs, mixed-case IDs, and wrong resource prefixes are rejected. Location selection uses the returned location_key, never a location ID. A key can end in @language to select a non-default language for the location, for example ES/Andalusia/Malaga@en; an unqualified key uses the country's default language.

The server consumes the public ID contract from the published @bisibility/sdk package. Do not replace it with a local SDK link.

BISIBILITY_MCP_READ_ONLY accepts 1, true, yes, or on, ignoring case. When enabled, write tools are not registered and do not appear in tools/list.

BISIBILITY_MCP_TOOLSETS is an optional comma-separated allowlist. Valid toolsets are account, agent-reports, ai-visibility, alerts, analytics, backlinks, checks, competitors, domain-overview, keywords, notifications, project-context, projects, prompt-explorer, providers, rank-history, saved-keywords, saved-views, signals, site-audits, sitemaps, system, team, tokens, and webhooks. An unknown value prevents the server from starting. When the variable is unset, all toolsets are registered. The toolset filter and read-only mode compose. The allowlist is a scope control, not a way to improve tool selection.

Run

npm run build
BISIBILITY_API_KEY="bsb_key_live_..." node dist/stdio.js

When installed as a package, the bin is:

bisibility-mcp

Connect

After building the repository, connect Codex to the local stdio server:

codex mcp add bisibility \
  --env BISIBILITY_API_KEY="bsb_key_live_..." \
  --env BISIBILITY_BASE_URL="https://bisibility.com/api/v1" \
  -- node /absolute/path/to/bisibility-mcp/dist/stdio.js

The codex mcp add syntax above was verified against the Codex CLI. Replace the absolute path and credential before running it.

Other MCP clients commonly use a JSON configuration like this:

{
  "mcpServers": {
    "bisibility": {
      "command": "npx",
      "args": ["-y", "@bisibility/mcp"],
      "env": {
        "BISIBILITY_API_KEY": "bsb_key_live_...",
        "BISIBILITY_BASE_URL": "https://eu.bisibility.com/api/v1"
      }
    }
  }
}

If bisibility-mcp is installed on the client's PATH, use the package bin:

{
  "mcpServers": {
    "bisibility": {
      "command": "bisibility-mcp",
      "env": {
        "BISIBILITY_API_KEY": "bsb_key_live_...",
        "BISIBILITY_BASE_URL": "https://eu.bisibility.com/api/v1"
      }
    }
  }
}

Tools

Tools use unprefixed snake_case names and can be filtered with BISIBILITY_MCP_TOOLSETS. Tools shared with the built-in /api/mcp endpoint use the same names. The two transports have different tool inventories; check tools/list before switching.

Domain Overview tools always require a nonnegative whole-cent max_cost_cents cap. Use estimate_only: true together with max_cost_cents: 0 for the safe estimate-first step; provider estimates and returned charges may still contain fractional cents.

For rank results, read execution status and observation_completeness together with position. A null position with unknown or legacy coverage does not establish absence within Top N. Only complete coverage supports that conclusion; a positive position remains valid with truncated coverage. latest_successful_check means the most recent completed observation, which can itself have unknown coverage.

Backlinks history is optional. history_unavailable marks a history failure with confirmed cost while summary and links remain available. If accounting is unknown, the request stays failed (isError) and may carry the completed summary as current-response evidence: cost_cents is null and rows are not requested. That evidence is not a cached snapshot or a settled total, cannot be extended with load_more_backlink_rows, and does not survive reload.