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.22.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.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, alerts, analytics, backlinks, brand-visibility, checks, competitors, domain-overview, keywords, notifications, page-indexing, project-context, projects, prompt-explorer, prompt-research, prompt-tracker, 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.

View tool names in this source checkout

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
• get_page_indexing_report
• list_page_indexing_urls
• get_page_indexing_settings
• update_page_indexing_settings
• list_search_index_sitemaps
• get_search_index_sitemap
• inspect_search_index_urls
• 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
• get_search_performance_totals
• 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_brand_visibility
• get_ai_research_catalog
• compare_ai_prompts
• run_site_audit
• list_site_audits
• get_site_audit

• list_prompt_tracker_topics
• create_prompt_tracker_topic
• update_prompt_tracker_topic
• archive_prompt_tracker_topic
• list_prompt_tracker_prompts
• create_prompt_tracker_prompt
• update_prompt_tracker_prompt
• archive_prompt_tracker_prompt
• list_prompt_tracker_schedules
• create_prompt_tracker_schedule
• update_prompt_tracker_schedule
• archive_prompt_tracker_schedule
• preview_prompt_tracker_run
• create_prompt_tracker_run
• list_prompt_tracker_runs
• get_prompt_tracker_run
• list_prompt_tracker_samples
• cancel_prompt_tracker_run
• retry_prompt_tracker_run
• get_prompt_tracker_history
• get_prompt_tracker_trends
• export_prompt_tracker_evidence
• suggest_prompt_research_prompts
• accept_prompt_research_suggestions
• `prompt_research_suggestions