Listable Directory Builder

Listable MCP 服务

通过自然对话，让 Claude、Cursor 和其他 AI 助手管理你的 Listable 目录网站。

Listable 是一个用于构建目录网站的平台，可用于打造餐厅指南、企业目录、旅行列表和细分主题精选网站。它的 MCP（模型上下文协议）服务会将所有网站管理操作作为结构化工具提供，供 AI 助手调用。

你可以向 AI 提出这类要求：

• “将布鲁克林的 20 家意大利餐厅添加到我的美食目录中。”
• “导入我粘贴的 CSV 中的这些列表。”
• “为首页设置 SEO 元标题和描述。”
• “在页眉菜单中添加一个分类下拉菜单。”
• “创建一个关于页面，介绍我们的使命并列出精选列表。”

功能

约 47 个工具，分为以下几组：

分组	工具
项目	列出、获取、发现架构
项目条目（列表）	列出（分页、筛选）、获取、创建、更新、删除、批量创建（每次最多 100 个）
分类	完整的 CRUD、分类树、冲突检查
自定义字段	列出、创建、更新、删除（文本、数字、日期、URL、复选框、选择、电话、地址、图片）
页面 + 区块	列出页面、获取/更新页面区块、管理全局区块区域（首页主视觉区、首页主体、详情页、分类页面）
表单	列出、获取、创建、更新、删除；管理表单字段
设置	菜单、脚本、SEO、URL 结构、主题
重定向	完整的 CRUD
上传	上传用于列表和页面的图片/文件

AI 会被告知先调用 get_schema，以便使用正确的自定义字段和区块类型进行编辑。破坏性操作（删除、完整替换区块、更改 URL 结构、覆盖脚本）执行前会请求确认。

两种连接方式

	OAuth（推荐）	静态 API 密钥（此软件包）
身份验证方式	客户端打开浏览器，你登录 Listable 并选择要授权的项目，即可完成	你在管理后台创建密钥，然后将其粘贴到客户端配置中
适用范围	Claude.ai 网页版、Claude Code、Cursor，以及任何支持 HTTP MCP + OAuth 发现的客户端	Claude Desktop（不支持 HTTP 传输），或任何需要静态令牌连接的场景
设置方式	粘贴一个 URL	安装此软件包 + 创建并粘贴密钥

如果你的客户端支持 HTTP MCP 传输，则无需使用中间层——请参阅下方的 OAuth 设置。仅 Claude Desktop 等只支持 stdio 的客户端需要 npm 软件包（listable-mcp）。

OAuth 设置（无需安装）

MCP 端点：

https://app.get-listable.com/api/v1/external/mcp

客户端连接时若未提供 bearer 令牌，服务会返回 401，以及指向 /.well-known/oauth-protected-resource 的 WWW-Authenticate 发现提示。客户端会根据提示跳转到登录页面，要求你批准权限范围（包括选择要授权的项目），并自动获取令牌。访问令牌有效期为 1 小时，并会在 1 个月内静默续期。

Claude.ai（网页版）

设置 → 集成 → 添加自定义集成 → 粘贴：

https://app.get-listable.com/api/v1/external/mcp

Claude.ai 会将你跳转到 Listable 登录，并选择该集成可以访问的项目。你可以随时在 Listable 管理后台的 API Keys 页面撤销授权。

Claude Code

claude mcp add --transport http listable https://app.get-listable.com/api/v1/external/mcp

Claude Code 首次使用时会在浏览器中完成 OAuth 流程。在会话中输入 /mcp 进行验证。

Cursor

在 设置 → MCP 中添加一个 HTTP 服务：

• 名称：listable
• URL：https://app.get-listable.com/api/v1/external/mcp

Cursor 首次连接时会启动 OAuth 流程。

Stdio 回退（此 npm 包）

对于 Claude Desktop（目前尚不支持 HTTP MCP）或任何仅支持 stdio 的客户端，请使用此方式。你需要先创建 API 密钥：

1. 在 Listable 管理后台打开 API Keys：https://app.get-listable.com/my-account/api-keys
2. 点击 Create a new API key，为密钥命名（例如“Claude Desktop”），并可选择将其限定为特定项目
3. 复制密钥——它只会显示一次

Claude Desktop

打开 Settings → Developer → Edit Config（claude_desktop_config.json）并添加：

{
  "mcpServers": {
    "listable": {
      "command": "npx",
      "args": ["-y", "listable-mcp"],
      "env": {
        "LISTABLE_API_TOKEN": "lst_..."
      }
    }
  }
}

完全退出并重启 Claude Desktop。Listable 的工具会显示在 Search and tools 菜单中。

其他 stdio 客户端

任何可以启动子进程的 MCP 客户端都能运行 npx -y listable-mcp，并在环境中传入 LISTABLE_API_TOKEN。

全局安装（可选）

如果你不想每次启动时都依赖 npx 解析：

npm install -g listable-mcp

然后让客户端直接调用 listable-mcp 二进制文件，而不是 npx -y listable-mcp。

配置

环境变量	必填	默认值	用途
LISTABLE_API_TOKEN	是	—	来自 https://app.get-listable.com/my-account/api-keys 的 API 密钥
LISTABLE_MCP_URL	否	https://app.get-listable.com/api/v1/external/mcp	覆盖上游端点（可自托管的 Listable 或暂存环境）

速率限制

• Growth 计划：每分钟 60 次请求，每月 750 次工具调用
• Pro 计划：每分钟 300 次请求，每月调用次数不限

达到任一限制时，会返回带有 retry_after（每分钟限制）或 quota_reset_at（月度限制）的 429。处理批量任务时，AI 更倾向于使用 bulk_create_items（每次调用最多创建 100 个列表项），而不是多次单独创建。

安全

工具描述会指示 AI：

• 先进行探查——编辑前调用 get_schema，确保更改使用正确的自定义字段和区块类型
• 确认破坏性操作——删除、替换整页区块、更改 URL 结构以及覆盖脚本时，都会要求明确确认
• 编辑前备份——在上下文中保留之前的状态，以便出错时恢复
• 追加而非替换——脚本（分析、跟踪）会追加到现有内容中

每次工具调用都会记录到其操作的项目中。在 Listable 管理后台的 Project → API 查看时间线——可按来源（MCP 或 REST）筛选，记录保留 30 天。

撤销访问权限

• OAuth 授权：与手动创建的密钥一起显示在 API Keys 页面中。可在该页面撤销。
• 静态 API 密钥：在同一个 API Keys 页面撤销。AI 客户端下次调用时会收到 401 错误。

故障排除

stdio 适配器出现“Unauthenticated”错误——确认在启动客户端的同一个 shell 或配置块中设置了 LISTABLE_API_TOKEN。在 Claude Desktop 中，JSON 配置里的 env 映射必须包含此密钥。

OAuth 循环 / 浏览器未重定向回来——确保客户端的重定向 URL 可访问。有些客户端使用 localhost 回调；Cookie 或弹窗拦截器可能会中断此流程。

“Tool not available”——重启客户端（Claude Desktop 需要完全退出后重新打开）。在 Claude Code 中，运行 /mcp 确认 Listable 已连接。

特定项目返回 403——你的令牌受范围限制。OAuth：重新进行授权并选择更多项目。静态密钥：创建一个不限定项目范围的新密钥。

链接

• Listable：https://get-listable.com
• API 和 MCP 文档：https://app.get-listable.com/my-account/api-docs
• Model Context Protocol：https://modelcontextprotocol.io

许可证

MIT — 参见 LICENSE。