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

An agent that receives a write-scoped or admin credential can create and change project data. Provider-backed Domain Overview tools can also spend the project's own provider budget on a cache miss. Every Domain Overview call requires an explicit nonnegative integer max_cost_cents. For the safe estimate-first step, call analyze_domain_overview with estimate_only: true and max_cost_cents: 0; use the same zero cap for a cache-only attempt. A positive value caps the permitted provider charge.

The destructive surface includes delete_project, delete_keyword, bulk_update_keywords when its operation is delete, delete_webhook, delete_alert_rule, delete_saved_keyword, delete_saved_view, remove_team_member, remove_competitor, disconnect_provider, revoke_api_key, revoke_personal_token, revoke_team_invite, and revoke_migration_token. Revoking the credential used by the server can immediately lock the server out.

Use read-only mode and a narrow toolset allowlist as defense in depth:

export BISIBILITY_MCP_READ_ONLY="1"
export BISIBILITY_MCP_TOOLSETS="projects,keywords,checks,rank-history,alerts"

Content returned by the API is untrusted input that reaches the model. Project names, keyword phrases, alert text, and similar tracked data can contain hostile instructions intended to steer an agent that also has write tools. Keep credentials and registered toolsets as narrow as the workflow permits, and enable client-side confirmation for tool calls when the MCP client supports it.

HTTP Transport

This package ships stdio transport only. The code is split so an HTTP transport can reuse the same server factory:

import { createBisibilityClientFromEnv, createBisibilityMcpServer } from "@bisibility/mcp";

const client = createBisibilityClientFromEnv();
const server = createBisibilityMcpServer({ client });

An HTTP entry point can wrap that server with the official SDK HTTP transport, such as StreamableHTTPServerTransport, in a Node, Worker, or hosted adapter.

Development

npm run lint
npm run typecheck
npm test
npm run build

License

Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.