@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_…[redacted]"
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_…[redacted]" 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_…[redacted]" \
  --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_…[redacted]",
        "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_…[redacted]",
        "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.

| Area | Examples | | --- | --- | | Discovery | Health, capabilities, provider rates, and cost estimates | | Rank tracking | Projects, keywords, checks, rank history, and sitemaps | | Analytics | Traffic snapshots, query statistics, signals, backlinks, and Domain Overview | | Agent analysis | Project context, saved reports, AI visibility, synthetic prompt comparisons, and bounded site audits | | Collaboration | Alerts, team members, invitations, and notifications | | Administration | Providers, API keys, personal tokens, webhooks, and migration tokens |

<details> <summary>View tool names in this source checkout</summary>

This list describes the source checkout and its unreleased changes. See the distribution status for currently published package and directory versions. The hosted endpoint has its own inventory.

• get_session_profile

• get_health

• get_capabilities

• get_cloud_import_compatibility

• get_provider_rates

• get_cost_estimate

• get_me

• update_me

• list_projects

• create_project

• get_project

• search_locations

• update_project

• delete_project

• get_project_defaults

• preview_project_defaults

• update_project_defaults

• list_keywords

• list_ranked_keyword_suggestions

• research_keywords

• estimate_keyword_research_cost

• analyze_backlinks

• estimate_backlinks_cost

• load_more_backlink_rows

• analyze_domain_overview

• estimate_domain_overview_cost

• load_domain_overview_history

• load_domain_overview_keywords

• load_domain_overview_pages

• get_keyword_metrics

• add_keywords

• get_keyword

• update_keyword

• set_keyword_target_url

• delete_keyword

• bulk_update_keywords

• run_rank_check

• get_rank_history

• export_rank_history | list_rank_check_runs | Read retained run outcomes and continuation cursors, including blocked and cancelled executions without checks. | | get_rank_check_run | Read one retained execution without launching or retrying a check. |

• list_local_monitor_runs

• get_local_monitor_run_results

• list_local_monitor_point_listings

• list_local_monitor_point_history

• export_local_monitor_run

• list_sitemap_monitors

• enable_sitemap_monitor

• disable_sitemap_monitor

• get_rank_check_result

• create_signal

• list_signals

• list_traffic_snapshots

• list_search_performance_query_stats

• sync_project_traffic

• list_api_keys

• create_api_key

• revoke_api_key

• list_project_api_keys

• create_project_api_key

• list_personal_tokens

• create_personal_token

• revoke_personal_token

• list_webhooks

• create_webhook

• update_webhook

• delete_webhook

• list_alert_rules

• create_alert_rule

• update_alert_rule

• delete_alert_rule

• list_triggered_alerts

• mute_triggered_alert

• mark_project_alerts_read

• list_team_members

• list_team_invites

• create_team_invite

• revoke_team_invite

• resend_team_invite

• update_team_member_role

• remove_team_member

• list_providers

• connect_provider (primary: true is a legacy alias for priority 0)

• test_provider_connection

• update_provider_settings

• set_provider_enabled

• set_provider_priority

• set_primary_provider (legacy: true promotes priority 0; false is a no-op)

• disconnect_provider

• list_saved_keywords

• create_saved_keywords

• delete_saved_keyword

• list_saved_views

• create_saved_view

• delete_saved_view

• list_competitors

• add_competitor

• remove_competitor

• get_notification_preferences

• update_notification_preferences

• list_migration_tokens

• mint_migration_token

• revoke_migration_token

• get_project_context

• update_project_context

• list_agent_reports

• create_agent_report

• get_agent_report

• analyze_ai_visibility

• get_ai_research_catalog

• compare_ai_prompts

• run_site_audit

• list_site_audits

• get_site_audit

• list_ai_tracking_topics

• create_ai_tracking_topic

• update_ai_tracking_topic

• archive_ai_tracking_topic

• list_ai_tracking_prompts

• create_ai_tracking_prompt

• update_ai_tracking_prompt

• archive_ai_tracking_prompt

• list_ai_tracking_schedules

• create_ai_tracking_schedule

• update_ai_tracking_schedule

• archive_ai_tracking_schedule

• preview_ai_tracking_run

• create_ai_tracking_run

• list_ai_tracking_runs

• get_ai_tracking_run

• list_ai_tracking_samples

• cancel_ai_tracking_run

• retry_ai_tracking_run

• get_ai_tracking_history

• get_ai_tracking_trends

• export_ai_tracking_evidence

• suggest_ai_tracking_prompts

• accept_ai_tracking_suggestions

• ai_tracking_suggestions_preview

• ai_tracking_suggestions_generate

</details>

All protected tools use the configured BISIBILITY_API_KEY. Tools that accept an idempotency_key forward it as the API Idempotency-Key request option. The key is required for create_ai_tracking_run, retry_ai_tracking_run, and ai_tracking_suggestions_generate; generation requires a UUID. Other tools expose optional