{
  "markdown": "# @bisibility/mcp\n\n> Part of [bisibility](https://github.com/CorgiCorner/bisibility) - an open-source SEO\n> platform for keyword research, backlink analysis, and Google rank tracking. This\n> repository contains the MCP server that exposes bisibility tools to AI agents.\n>\n> [Docs](https://bisibility.com/docs) ·\n> [API reference](https://bisibility.com/docs/api/overview) ·\n> [Roadmap](https://bisibility.com/roadmap)\n>\n> **Status:** Developer preview.\n\n## Distribution\n\n[![npm version](https://img.shields.io/npm/v/%40bisibility%2Fmcp?label=npm)](https://www.npmjs.com/package/@bisibility/mcp)\n[![Official MCP Registry](https://img.shields.io/badge/Official_MCP_Registry-active-2ea44f)](https://registry.modelcontextprotocol.io/v0.1/servers?search=com.bisibility%2Fmcp)\n[![Glama](https://img.shields.io/badge/Glama-listed-2ea44f)](https://glama.ai/mcp/servers/CorgiCorner/bisibility-mcp)\n[![smithery badge](https://smithery.ai/badge/bisibility/mcp)](https://smithery.ai/servers/bisibility/mcp)\n\n[Distribution status and release channels](https://github.com/CorgiCorner/bisibility-mcp/blob/main/docs/DISTRIBUTION.md)\n\nModel Context Protocol server for the bisibility REST API. It exposes stdio tools\nbacked by the published `@bisibility/sdk` package.\n\n## Requirements\n\n- Node.js 18 or newer\n- A bisibility API key\n- A bisibility API v1 base URL\n\n## Install\n\nRun the published stdio server without a global install:\n\n```sh\nnpx -y @bisibility/mcp\n```\n\nFor local development, install and build from this package directory:\n\nFrom this package directory:\n\n```sh\nnpm install\nnpm run build\n```\n\nThe SDK is consumed from the npm registry:\n\n```json\n\"@bisibility/sdk\": \"^0.10.0\"\n```\n\n### MCPB bundle\n\nDirectories and clients that support MCPB can distribute bisibility as a one-click local bundle.\nThe bundle includes the stdio server and all production dependencies, but never a bisibility\ncredential. The client collects configuration during installation.\n\nBuild the upload artifact with:\n\n```sh\nnpm ci\nnpm run build\nnpm run build:mcpb\n```\n\nThe versioned file is written to `artifacts/`.\n\n## Environment\n\n```sh\nexport BISIBILITY_API_KEY=\"bsb_pat_live_...\"\nexport BISIBILITY_BASE_URL=\"https://eu.bisibility.com/api/v1\"\nexport BISIBILITY_PROJECT_ID=\"prj_...\"\nexport BISIBILITY_MCP_READ_ONLY=\"1\"\nexport BISIBILITY_MCP_TOOLSETS=\"projects,keywords,checks,rank-history\"\n```\n\n`BISIBILITY_BASE_URL` is optional and defaults to `https://eu.bisibility.com/api/v1`. For self-hosted\ninstalls, set it to your API v1 root, for example `https://rank.example/api/v1`.\n`BISIBILITY_API_KEY` accepts a project key (`bsb_key_live_...`) or personal access\ntoken (`bsb_pat_live_...`). Set optional `BISIBILITY_PROJECT_ID` as the default\n`X-Bisibility-Project` selector for project-implicit PAT tools; a tool's\noptional `project_id` argument overrides it for that call. Every resource ID\naccepted by the MCP server, including `BISIBILITY_PROJECT_ID`, must use the\ncurrent typed public ID format: a canonical lowercase prefix plus `_` and a\n24-character lowercase suffix, for example `prj_a1b2c3d4e5f6g7h8j9k0m2n3`.\nMalformed IDs, mixed-case IDs, and wrong resource prefixes are rejected.\nLocation selection uses the returned `location_key`, never a location ID. A key can end in\n`@language` to select a non-default language for the location, for example\n`ES/Andalusia/Malaga@en`; an unqualified key uses the country's default language.\n\nThe server consumes the public ID contract from the published\n`@bisibility/sdk` package. Do not replace it with a local SDK link.\n\n`BISIBILITY_MCP_READ_ONLY` accepts `1`, `true`, `yes`, or `on`, ignoring case. When enabled,\nwrite tools are not registered and do not appear in `tools/list`.\n\n`BISIBILITY_MCP_TOOLSETS` is an optional comma-separated allowlist. Valid toolsets are `account`,\n`alerts`, `analytics`, `backlinks`, `checks`, `competitors`, `domain-overview`, `keywords`,\n`notifications`, `projects`, `providers`, `rank-history`, `saved-views`, `signals`, `sitemaps`,\n`system`, `team`, `tokens`, and `webhooks`. An unknown value prevents the server from starting.\nWhen the variable is unset, all toolsets are registered. The toolset filter and read-only mode\ncompose. The allowlist is a scope control, not a way to improve tool selection.\n\n## Run\n\n```sh\nnpm run build\nBISIBILITY_API_KEY=\"bsb_key_live_...\" node dist/stdio.js\n```\n\nWhen installed as a package, the bin is:\n\n```sh\nbisibility-mcp\n```\n\n## Connect\n\nAfter building the repository, connect Codex to the local stdio server:\n\n```sh\ncodex mcp add bisibility \\\n  --env BISIBILITY_API_KEY=\"bsb_key_live_...\" \\\n  --env BISIBILITY_BASE_URL=\"https://bisibility.com/api/v1\" \\\n  -- node /absolute/path/to/bisibility-mcp/dist/stdio.js\n```\n\nThe `codex mcp add` syntax above was verified against the Codex CLI. Replace the\nabsolute path and credential before running it.\n\nOther MCP clients commonly use a JSON configuration like this:\n\n```json\n{\n  \"mcpServers\": {\n    \"bisibility\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@bisibility/mcp\"],\n      \"env\": {\n        \"BISIBILITY_API_KEY\": \"bsb_key_live_...\",\n        \"BISIBILITY_BASE_URL\": \"https://eu.bisibility.com/api/v1\"\n      }\n    }\n  }\n}\n```\n\nIf `bisibility-mcp` is installed on the client's `PATH`, use the package bin:\n\n```json\n{\n  \"mcpServers\": {\n    \"bisibility\": {\n      \"command\": \"bisibility-mcp\",\n      \"env\": {\n        \"BISIBILITY_API_KEY\": \"bsb_key_live_...\",\n        \"BISIBILITY_BASE_URL\": \"https://eu.bisibility.com/api/v1\"\n      }\n    }\n  }\n}\n```\n\n## Tools\n\nTools use unprefixed `snake_case` names and can be filtered with\n`BISIBILITY_MCP_TOOLSETS`. The names match the built-in `/api/mcp` endpoint, so clients can\nswitch transports without rewriting tool calls.\n\nDomain Overview tools always require a nonnegative whole-cent `max_cost_cents`\ncap. Use `estimate_only: true` together with `max_cost_cents: 0` for the safe\nestimate-first step; provider estimates and returned charges may still contain\nfractional cents.\n\n| Area | Examples |\n| --- | --- |\n| Discovery | Health, capabilities, provider rates, and cost estimates |\n| Rank tracking | Projects, keywords, checks, rank history, and sitemaps |\n| Analytics | Traffic snapshots, query statistics, signals, backlinks, and Domain Overview |\n| Collaboration | Alerts, team members, invitations, and notifications |\n| Administration | Providers, API keys, personal tokens, webhooks, and migration tokens |\n\n<details>\n<summary>View all registered tool names</summary>\n\n- `get_health`\n- `get_capabilities`\n- `get_cloud_import_compatibility`\n- `get_provider_rates`\n- `get_cost_estimate`\n- `get_me`\n- `update_me`\n- `list_projects`\n- `create_project`\n- `get_project`\n- `search_locations`\n- `update_project`\n- `delete_project`\n- `get_project_defaults`\n- `update_project_defaults`\n- `list_keywords`\n- `list_ranked_keyword_suggestions`\n- `research_keywords`\n- `analyze_backlinks`\n- `load_more_backlink_rows`\n- `analyze_domain_overview`\n- `load_domain_overview_history`\n- `load_domain_overview_keywords`\n- `load_domain_overview_pages`\n- `get_keyword_metrics`\n- `add_keywords`\n- `get_keyword`\n- `update_keyword`\n- `set_keyword_target_url`\n- `delete_keyword`\n- `bulk_update_keywords`\n- `run_rank_check`\n- `get_rank_history`\n- `export_rank_history`\n- `list_sitemap_monitors`\n- `enable_sitemap_monitor`\n- `disable_sitemap_monitor`\n- `get_rank_check_result`\n- `create_signal`\n- `list_signals`\n- `list_traffic_snapshots`\n- `list_search_performance_query_stats`\n- `sync_project_traffic`\n- `list_api_keys`\n- `create_api_key`\n- `revoke_api_key`\n- `list_project_api_keys`\n- `create_project_api_key`\n- `list_personal_tokens`\n- `create_personal_token`\n- `revoke_personal_token`\n- `list_webhooks`\n- `create_webhook`\n- `update_webhook`\n- `delete_webhook`\n- `list_alert_rules`\n- `create_alert_rule`\n- `update_alert_rule`\n- `delete_alert_rule`\n- `list_triggered_alerts`\n- `mute_triggered_alert`\n- `mark_project_alerts_read`\n- `list_team_members`\n- `list_team_invites`\n- `create_team_invite`\n- `revoke_team_invite`\n- `resend_team_invite`\n- `update_team_member_role`\n- `remove_team_member`\n- `list_providers`\n- `connect_provider` (`primary: true` is a legacy alias for priority `0`)\n- `test_provider_connection`\n- `update_provider_settings`\n- `set_provider_enabled`\n- `set_provider_priority`\n- `set_primary_provider` (legacy: true promotes priority `0`; false is a no-op)\n- `disconnect_provider`\n- `list_saved_keywords`\n- `create_saved_keywords`\n- `delete_saved_keyword`\n- `list_saved_views`\n- `create_saved_view`\n- `delete_saved_view`\n- `list_competitors`\n- `add_competitor`\n- `remove_competitor`\n- `get_notification_preferences`\n- `update_notification_preferences`\n- `list_migration_tokens`\n- `mint_migration_token`\n- `revoke_migration_token`\n\n</details>\n\nAll protected tools use the configured `BISIBILITY_API_KEY`. Write tools accept an optional\n`idempotency_key`, which is forwarded as the API `Idempotency-Key` request option.\n\nThe list above is asserted by a test (`test/tools.test.ts`), so it stays in sync with the\nregistered tool surface.\n\n## Security\n\nThe credential's scope is the primary authorization control, and the server accepts two kinds.\nA project key (`bsb_key_live_...`) belongs to exactly one project, which bounds the damage from a\nleak and makes it a good fit for a single-project or machine setup. A personal access token\n(`bsb_pat_live_...`) covers the projects you are a member of, so one token serves them all; its\neffective access in each project is the lower of the token's scope and your role there, meaning\na token never grants more than the person behind it. Use `BISIBILITY_PROJECT_ID` to set the\ndefault project for a token that spans several, as described under Environment above.\n\nWhichever kind you use, create it with a `read` scope for assistant use whenever possible, and\ndo not grant `admin` unless the assistant needs an administrative API operation. Server-side\nfiltering narrows the tools presented to the model, but it does not expand or replace the\npermissions of the configured credential.\n\nAn agent that receives a write-scoped or admin credential can create and change project data.\nProvider-backed Domain Overview tools can also spend the project's own provider budget on a cache\nmiss. Every Domain Overview call requires an explicit nonnegative integer `max_cost_cents`. For the\nsafe estimate-first step, call `analyze_domain_overview` with `estimate_only: true` and\n`max_cost_cents: 0`; use the same zero cap for a cache-only attempt. A positive value caps the\npermitted provider charge.\n\nThe destructive surface includes `delete_project`, `delete_keyword`,\n`bulk_update_keywords` when its operation is `delete`, `delete_webhook`,\n`delete_alert_rule`, `delete_saved_keyword`, `delete_saved_view`,\n`remove_team_member`, `remove_competitor`,\n`disconnect_provider`, `revoke_api_key`,\n`revoke_personal_token`, `revoke_team_invite`, and\n`revoke_migration_token`. Revoking the credential used by the server can immediately\nlock the server out.\n\nUse read-only mode and a narrow toolset allowlist as defense in depth:\n\n```sh\nexport BISIBILITY_MCP_READ_ONLY=\"1\"\nexport BISIBILITY_MCP_TOOLSETS=\"projects,keywords,checks,rank-history,alerts\"\n```\n\nContent returned by the API is untrusted input that reaches the model. Project names, keyword\nphrases, alert text, and similar tracked data can contain hostile instructions intended to steer\nan agent that also has write tools. Keep credentials and registered toolsets as narrow as the\nworkflow permits, and enable client-side confirmation for tool calls when the MCP client supports\nit.\n\n## HTTP Transport\n\nThis package ships stdio transport only. The code is split so an HTTP transport can reuse the same\nserver factory:\n\n```ts\nimport { createBisibilityClientFromEnv, createBisibilityMcpServer } from \"@bisibility/mcp\";\n\nconst client = createBisibilityClientFromEnv();\nconst server = createBisibilityMcpServer({ client });\n```\n\nAn HTTP entry point can wrap that server with the official SDK HTTP transport, such as\n`StreamableHTTPServerTransport`, in a Node, Worker, or hosted adapter.\n\n## Development\n\n```sh\nnpm run lint\nnpm run typecheck\nnpm test\nnpm run build\n```\n\n## License\n\nLicensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).\n",
  "bytes": 12224,
  "sha": "f02521fe0009f83179f1f8b2faec4551b76f1301ccea1e1921c7b1fb0901eb53",
  "repo_slug": "corgicorner/bisibility-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_bisibility_mcp_abd647e9/readme"
}