@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.12.0"

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/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, alerts, analytics, backlinks, checks, competitors, domain-overview, keywords, notifications, projects, providers, rank-history, saved-views, signals, 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. The names match the built-in /api/mcp endpoint, so clients can switch transports without rewriting tool calls.

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.

All protected tools use the configured BISIBILITY_API_KEY. Write tools accept an optional idempotency_key, which is forwarded as the API Idempotency-Key request option.

The list above is asserted by a test (test/tools.test.ts), so it stays in sync with the registered tool surface.

Security

The credential's scope is the primary authorization control, and the server accepts two kinds. A project key (bsb_key_live_...) belongs to exactly one project, which bounds the damage from a leak and makes it a good fit for a single-project or machine setup. A personal access token (bsb_pat_live_...) covers the projects you are a member of, so one token serves them all; its effective access in each project is the lower of the token's scope and your role there, meaning a token never grants more than the person behind it. Use BISIBILITY_PROJECT_ID to set the default project for a token that spans several, as described under Environment above.

Whichever kind you use, create it with a read scope for assistant use whenever possible, and do not grant admin unless the assistant needs an administrative API operation. Server-side filtering narrows the tools presented to the model, but it does not expand or replace the permissions of the configured credential.