Ethora MCP Server

Ethora MCP服务器（模型上下文协议）

](https://www.npmjs.com/package/@ethora/mcp-server) ](#) 

  

单击安装光标和VS代码（上面的按钮）。关于Claude Code、Claude Desktop、GitHub Copilot、Gemini CLI、Codex CLI、Windsurf和Cline，请参阅 与MCP客户端一起使用 在......下面

MCP（模型上下文协议）CLI/服务器，将流行的MCP客户端连接到 埃波拉 开源平台 内置AI代理/聊天机器人框架的聊天和消息平台。这通过stdio在开发人员计算机上本地运行，而不是作为托管的Ethora服务运行。\ 使用它从 光标, VS代码MCP, 克劳德桌面，或 风帆/克莱恩 管理应用程序和聊天室、广播消息、使用RAG源部署AI代理/聊天机器人，以及自动化B2B配置工作流程。（ERC-20钱包工具也包括在内——见下面的工具列表。）

• npm：
• 默认Ethora API： https://api.chat.ethora.com/v1 （斯瓦格： )

______________________________________________________________________

✨ 你得到了什么

• 直接从IDE或AI代理客户端（Cursor、VS Code MCP、Claude Desktop、Windsurf/Cline）与Ethora平台对话。
• 两者 用户身份验证 流（登录/注册、文件、所有者/管理员端点）和 B2B/应用令牌 流（租户配置、广播作业、异步用户批处理、AI机器人配置）。
• 为最常见的Ethora工作流程（Vite/Next聊天组件设置、B2B引导、AI机器人启用、RAG来源）提供内置的食谱、提示和生成器。
• 标准工具响应包络({ ok, ts, meta, data | error })因此，代理代码可以一致地推断成功/失败。

🚦 只是想试试？（60秒快速入门）

暂时不要阅读身份验证模式。一旦服务器连接到客户端，请让您的代理按顺序运行：

1. ethora-doctor -确认服务器已启动并且可以访问Ethora API。不需要凭据。
2. ethora-configure 和你一起 appJwt → ethora-auth-use-user → ethora-user-login 使用电子邮件+密码。
3. ethora-app-list --你加入了；这列出了你的应用程序。

这就是本地开发者的道路。需要服务器端自动化吗？跳转到 B2B模式.随时迷路，打电话 ethora-help -它读取您当前的状态并告诉您下一个呼叫。

🔐 两种典型的使用模式

1） 用户身份验证模式

最适合：

• 开发人员在本地试用Ethora
• 租户管理员/应用程序所有者手动使用MCP
• 以…开头的流程 ethora-user-login

它是如何工作的：

• 配置 ETHORA_APP_JWT 一次用于登录/注册引导
• 切换到 ethora-auth-use-user
• 呼叫 ethora-user-login
• 使用用户身份验证工具，如文件和传统所有者/管理员端点

2） B2B模式

最适合：

• 永久后端集成
• 合作伙伴配置流
• 在没有人类用户会话的情况下操作Ethora的自主代理

它是如何工作的：

• 配置 ETHORA_B2B_TOKEN
• 切换到 ethora-auth-use-b2b 对于明确的租户参与者 /v2/apps/:appId/... 路线
• 可选择切换到 ethora-auth-use-app 之后 ethora-app-select 当你想要应用程序范围内的便利路线时 appToken

经验法则：

• 首次本地使用通常从 用户身份验证
• 可重复的自动化通常始于 公司对公司业务，然后经常进入 应用程序令牌 一个选定应用程序的模式

提示和资源（P2:面向开发的文档）

• 资源 （可将文档加载到上下文中）

- ethora://docs/auth-map --appJwt vs appToken vs b2bToken - ethora://docs/chat-component/quickstart --Vite/Next快速入门+替换演示令牌 - ethora://docs/sdk-backend/quickstart --后端集成快速入门 - ethora://docs/recipes --常用工具序列（广播/源/文件/bot）

• 提示

- ethora-auth-map - ethora-vite-quickstart - ethora-nextjs-quickstart - ethora-backend-sdk-quickstart - ethora-recipes

生成器（无外壳，无文件写入）

• ethora-generate-chat-component-app-tsx --准备粘贴 App.tsx 代码片段 @ethora/chat-component
• ethora-generate-env-examples — .env.example 模板用于：

- 前端聊天组件 - 后端SDK集成 - MCP使用(ETHORA_API_URL, ETHORA_APP_JWT, ETHORA_B2B_TOKEN)

• ethora-generate-b2b-bootstrap-runbook --用于B2B引导的最小“按顺序调用这些MCP工具”runbook

提示：无需调用即可列出可运行的食谱 ethora-help，呼叫 ethora-run-recipe 随着 goal: "auto" 并省略 recipeId.

• 会话/配置

- ethora-configure -设置此MCP会话的API URL和应用程序JWT/B2B令牌/appToken - ethora-status -显示已配置的API URL、活动身份验证模式以及存在的凭据 - ethora-help --面向任务的帮助（推荐下一个电话+基于当前状态的“一键式食谱”） - ethora-run-recipe --按id执行内置配方（顺序步骤；无shell，无文件写入） - ethora-doctor -为用户和B2B使用验证配置+ping配置的Ethora API - ethora-app-select --选择当前appId并可选择设置appToken - ethora-auth-use-app --切换到应用令牌身份验证模式以进行应用范围的操作 - ethora-auth-use-user --切换到用户会话身份验证模式 - ethora-auth-use-b2b --切换到租户参与者B2B x-custom-token 身份验证模式

• 聊天（v2）

- ethora-chats-broadcast-v2 --使用应用令牌身份验证或B2B+显式方式排队广播作业 appId - ethora-chats-broadcast-job-v2 --使用应用令牌身份验证或B2B+显式获取广播作业状态/结果 appId - ethora-wait-broadcast-job-v2 --使用应用令牌身份验证或B2B+显式方式轮询广播作业，直到完成/失败 appId - ethora-chats-message-v2 --通过应用程序聊天界面发送测试/自动化消息（需要应用程序令牌身份验证） - ethora-chats-history-v2 --读取私有或组会话的持久自动化/测试历史记录（需要应用令牌身份验证）

• 用户（v2异步批处理）

- ethora-users-batch-create-v2 --创建异步用户批处理作业（需要B2B身份验证） - ethora-users-batch-job-v2 --获取用户批处理作业状态/结果（需要B2B身份验证） - ethora-wait-users-batch-job-v2 --轮询用户批处理作业，直到完成/失败（需要B2B身份验证）

• 文件（v2）

• 机器人/代理（v2）

- ethora-bot-get-v2 --使用应用令牌身份验证或B2B+显式获取机器人状态/设置 appId

- ethora-bot-update-v2 --使用应用令牌身份验证或B2B+显式更新机器人设置 appId

- ethora-bot-enable-v2 --使用应用令牌身份验证或B2B+显式启用机器人 appId

- ethora-bot-disable-v2 --使用应用令牌身份验证或B2B+显式禁用机器人 appId

- ethora-bot-widget-v2 --获取小部件/嵌入配置和公共小部件URL元数据（应用令牌认证）

- ethora-agents-list-v2 --为当前应用程序所有者列出可重用的已保存代理（应用程序令牌身份验证）

- ethora-agents-get-v2 --获取一个可重用的已保存代理（应用令牌身份验证）

- ethora-agents-create-v2 --创建可重用的已保存代理（应用令牌身份验证）

- ethora-agents-update-v2 --更新可重用的已保存代理（应用令牌身份验证）

- ethora-agents-clone-v2 --克隆可重用的已保存代理（应用令牌身份验证）

- ethora-agents-activate-v2 --将已保存的代理绑定为所选应用程序的活动bot（应用程序令牌身份验证）

- ethora-bot-message-v2 --兼容性别名 ethora-chats-message-v2

- ethora-bot-history-v2 --兼容性别名 ethora-chats-history-v2

- ethora-files-upload-v2 --上传文件（需要用户身份验证）

- ethora-files-get-v2 --列出/获取文件（需要用户身份验证）

- ethora-files-delete-v2 --按id删除文件（需要用户身份验证）

• 来源

- ethora-sources-site-crawl --抓取URL（需要用户身份验证） - ethora-sources-site-reindex --按urlId重新索引URL（需要用户身份验证） - ethora-sources-site-delete-url --按URL删除（需要用户身份验证） - ethora-sources-site-delete-url-v2 --批量删除URL（需要用户身份验证） - ethora-sources-docs-upload --上传文档以供摄入（需要用户身份验证） - ethora-sources-docs-delete --按id删除摄入的文档（需要用户身份验证） - ethora-sources-site-crawl-v2 --使用应用令牌身份验证或B2B+显式抓取URL appId - ethora-sources-site-reindex-v2 --使用应用令牌身份验证或B2B+显式通过urlId重新索引URL appId - ethora-sources-site-crawl-v2-wait --用于爬网的单次调用长超时帮助程序（应用令牌身份验证） - ethora-sources-site-reindex-v2-wait --reindex的单次调用长超时帮助程序（应用令牌身份验证） - ethora-sources-site-list-v2 --使用应用令牌身份验证或B2B+显式列出已爬网的网站源和当前标签 appId - ethora-sources-site-tags-update-v2 --使用应用令牌身份验证或B2B+显式设置/更新已爬网站点源的标签 appId - ethora-sources-site-delete-url-v2 --使用应用令牌身份验证或B2B+显式方式逐个删除已爬网的URL appId - ethora-sources-site-delete-url-v2-batch --使用应用令牌身份验证或B2B+显式按id批量删除已爬网的源记录 appId - ethora-sources-docs-upload-v2 --使用应用令牌身份验证或B2B+显式上传文档以供摄入 appId - ethora-sources-docs-list-v2 --使用应用令牌身份验证或B2B+显式列出索引文档和当前标签 appId - ethora-sources-docs-tags-update-v2 --使用应用程序令牌身份验证或B2B+显式为索引文档设置/更新标签 appId - ethora-sources-docs-delete-v2 --使用应用令牌身份验证或B2B+显式按id删除文档 appId

• 身份验证和帐户

- ethora-user-login --登录用户（电子邮件+密码） - ethora-user-register --注册用户（电子邮件+名字/姓氏）

• 应用程序

- ethora-app-create --创建应用程序 - ethora-app-update --更新应用程序 - ethora-app-delete --删除应用程序 - ethora-app-list --列出应用程序 - ethora-b2b-app-create --使用B2B身份验证（x-custom-token）创建应用程序 - ethora-b2b-app-bootstrap-ai --创建应用程序→ 索引来源→ 配置/启用bot，包括运行时LLM选择（B2B自动化） - ethora-app-tokens-list-v2 --列出应用令牌元数据（B2B身份验证） - ethora-app-tokens-create-v2 --创建新的应用令牌（返回一次）（B2B身份验证） - ethora-app-tokens-rotate-v2 --轮转令牌（撤销旧令牌，返回新令牌一次）（B2B身份验证） - ethora-app-tokens-revoke-v2 --通过tokenId（幂等）撤销令牌（B2B身份验证） - ethora-b2b-app-provision --创建应用程序+创建令牌+配置房间+配置机器人，包括运行时LLM选择（B2B编排器）

• 聊天和客房

- ethora-app-get-default-rooms --列出默认房间 - ethora-app-get-default-rooms-with-app-id --给定应用程序的房间 - ethora-app-create-chat --为应用程序创建聊天 - ethora-app-delete-chat --删除聊天

• 钱包

- ethora-wallet-get-balance --获得平衡 - ethora-wallet-erc20-transfer --发送ERC-20代币

上面的工具名称反映了服务器暴露的功能区域。您的确切工具名称可能因版本而异；运行客户端的“列表工具”进行确认。

📦 安装/运行

先决条件

在开始之前，请确保您拥有以下内容：

• Node.js已安装在您的系统上（推荐18.x或更高版本）。

安装

服务器以npm包的形式分发，通常由MCP客户端通过以下方式启动 npx:

npx -y @ethora/mcp-server

不需要全局安装。

______________________________________________________________________

🔐 配置（环境变量）

此MCP服务器支持本地用户身份验证流和服务器端B2B流。

核心价值观：

• Ethora API URL （向何处发送请求）
• Ethora应用程序JWT （仅用于用户身份验证模式下的登录/注册引导）
• Ethora B2B代币 （用于租户参与者服务器到服务器的流）

您可以提供以下内容之一：

• 通过 环境变量，或
• 在运行时通过 ethora-configure 工具（内存中；MCP进程重新启动时重置）

支持的环境变量

• ETHORA_API_URL：API完整URL（例如： https://api.chat.ethora.com/v1, http://localhost:8080/v1)
• ETHORA_BASE_URL：基本主机URL（示例： https://api.chat.ethora.com, http://localhost:8080)\

如果提供，服务器将默认为 .../v1.

• ETHORA_APP_JWT：应用程序JWT字符串，通常以 JWT ...
• ETHORA_B2B_TOKEN：B2B服务器令牌 x-custom-token auth（JWT与 type=server)
• ETHORA_MCP_ENABLE_DANGEROUS_TOOLS：启用破坏性工具（默认：禁用）。设为 true 揭露：

- 应用程序删除工具 - 钱包转账工具 - 批量删除工具

安全： 从不 将App JWT、B2B令牌或appTokens提交到git。通过env-vars、MCP客户端密钥存储或您自己的后端配置它们。

______________________________________________________________________

🧱 标准响应信封（工具）

所有工具都以一致的信封返回JSON：

• 成功： { ok: true, ts, meta, data }
• 错误： { ok: false, ts, meta, error }，在哪里 error 包括：

- code：稳定字符串（首选API code，否则推断） - httpStatus：失败来自API调用时的HTTP状态 - requestId：如果API返回请求/关联id - hint：1行“下一步做什么”

______________________________________________________________________

🚀 与MCP客户端一起使用

每个客户端都运行相同的东西-- npx -y @ethora/mcp-server 超过stdio。存在一键按钮 光标 和 VS Code （此README的顶部）。其余的是一个简短的配置块或一行命令。

光标

使用 添加到光标 按钮上方，或手动： 设置→ MCP → 添加新的全局MCP服务器:

{
  "mcpServers": {
    "ethora": {
      "command": "npx",
      "args": ["-y", "@ethora/mcp-server"]
    }
  }
}

VS代码（和GitHub副本）

使用 在VS代码中安装 按钮上方，或添加 .vscode/mcp.json 文件（项目级）——注意关键是 servers:

{
  "servers": {
    "ethora": {
      "command": "npx",
      "args": ["-y", "@ethora/mcp-server"]
    }
  }
}

GitHub Copilot的 代理模式 在VS代码中读起来是一样的 .vscode/mcp.json --没有单独的设置。（对于用户级安装，请将 servers 块下 "mcp" 在您的用户设置JSON中。)

克劳德代码

一个命令：

claude mcp add ethora -- npx -y @ethora/mcp-server

添加 --scope user 使其在每个项目中都可用。证实 claude mcp list.

要预配置凭据，请将其作为env变量传递 -e （推荐超过 ethora-configure 工具——见下面的注释）：

claude mcp add ethora \
  -e ETHORA_API_URL=https://api.chat.ethora.com/v1 \
  -e ETHORA_B2B_TOKEN= \
  -- npx -y @ethora/mcp-server

秘密笔记： 更喜欢env-vars（如上）或MCP客户端的密钥存储作为凭据。这 ethora-configure 该工具同样有效，但它将秘密作为工具参数传递，这意味着它们最终会出现在对话记录中。将其用于快速本地测试，而不是用于您关心的令牌。

克劳德桌面

设置→ 开发者→ 编辑配置，打开 claude_desktop_config.json:

{
  "mcpServers": {
    "ethora": {
      "command": "npx",
      "args": ["-y", "@ethora/mcp-server"]
    }
  }
}

Gemini CLI

添加 ~/.gemini/settings.json （全球）或 .gemini/settings.json （每个项目）：

{
  "mcpServers": {
    "ethora": {
      "command": "npx",
      "args": ["-y", "@ethora/mcp-server"]
    }
  }
}

Codex CLI

添加 ~/.codex/config.toml --请注意，表名为 mcp_servers （下划线； mcp-servers 被默默忽略）：

[mcp_servers.ethora]
command = "npx"
args = ["-y", "@ethora/mcp-server"]

帆板运动

设置→ 级联→ MCP服务器→ 查看原始配置 (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "ethora": {
      "command": "npx",
      "args": ["-y", "@ethora/mcp-server"]
    }
  }
}

克莱恩

打开MCP服务器面板并编辑 cline_mcp_settings.json:

{
  "mcpServers": {
    "ethora": {
      "command": "npx",
      "args": ["-y", "@ethora/mcp-server"]
    }
  }
}

______________________________________________________________________

🧪 快速测试

服务器显示为 连接的 在您的客户中：

• 跑 list tools （客户端命令）验证Ethora工具是否可用。
• 检查配置/连接：调用 ethora-doctor （或 ethora-status)
• 对于首次本地/手动测试：

- 呼叫 ethora-configure 随着 apiUrl / appJwt - 呼叫 ethora-auth-use-user - 呼叫 ethora-user-login - 然后尝试 ethora-app-list 或 ethora-wallet-get-balance

• 对于服务器端/B2B测试：

- 呼叫 ethora-configure 随着 apiUrl / b2bToken - 呼叫 ethora-auth-use-b2b - 然后尝试 ethora-b2b-app-create 或 ethora-app-tokens-list-v2

______________________________________________________________________

🧭 P1:B2B“创建应用程序”→ 索引来源→ 在一次通话中部署机器人

先决条件：

• 配置 ETHORA_API_URL （或致电 ethora-configure)
• 配置 ETHORA_B2B_TOKEN （或致电 ethora-configure 随着 b2bToken)
• 确保您的Ethora后端配置了AI服务URL/secrete（用于机器人激活）

建议流量：

• 呼叫 ethora-auth-use-b2b
• 呼叫 ethora-b2b-app-bootstrap-ai 与：

- displayName - 可选的 savedAgentId - 可选的 crawlUrl - 可选的 docs[] （base64） - enableBot: true - 可选的 llmProvider - 可选的 llmModel

它将：

• 创建应用程序（B2B）
• 设置当前应用程序上下文（尽力而为）
• 索引来源 /v2/sources/* （应用令牌身份验证）
• 配置和/或启用bot（尽最大努力）

有效载荷示例

最小（仅创建应用程序）：

{
  "displayName": "Acme AI Demo",
  "setAsCurrent": true
}

创建应用程序+抓取网站+启用机器人：

{
  "displayName": "Acme AI Demo",
  "savedAgentId": "6790abc1234567890def1111",
  "crawlUrl": "https://example.com",
  "followLink": true,
  "enableBot": true,
  "botTrigger": "/bot",
  "llmProvider": "openai",
  "llmModel": "gpt-4o-mini"
}

创建应用程序+上传文档+启用机器人：

{
  "displayName": "Acme AI Demo",
  "docs": [
    {
      "name": "faq.pdf",
      "mimeType": "application/pdf",
      "base64": "BASE64_PDF_CONTENT_HERE"
    }
  ],
  "enableBot": true,
  "llmProvider": "openai",
  "llmModel": "gpt-4o-mini"
}

配置应用程序+令牌+默认房间+机器人设置：

{
  "displayName": "Acme Support",
  "savedAgentId": "6790abc1234567890def1111",
  "tokenLabels": ["default", "staging"],
  "rooms": [
    { "title": "General" },
    { "title": "Support", "pinned": true }
  ],
  "enableBot": true,
  "botTrigger": "/bot",
  "botPrompt": "You are the Acme support assistant.",
  "botGreetingMessage": "Hello. How can I help?",
  "llmProvider": "openai",
  "llmModel": "gpt-4o-mini"
}

供应商/型号说明：

• 常见的价值观是 openai 和 openai-compatible.
• 有效的提供者/模型还必须由您的Ethora后端+AI服务环境启用。

______________________________________________________________________

🤖 应用程序自动化循环

一旦你已经选择了一个应用程序 appToken 身份验证：

• 呼叫 ethora-auth-use-app
• 呼叫 ethora-bot-get-v2 检查当前bot状态和提示设置
• 呼叫 ethora-sources-site-list-v2 和 ethora-sources-docs-list-v2 检查索引源
• 呼叫 ethora-sources-site-tags-update-v2 或 ethora-sources-docs-tags-update-v2 按标签组织检索
• 呼叫 ethora-chats-message-v2 / ethora-chats-history-v2 如果您的后端在同一API主机上暴露聊天自动化表面

示例：将检索标签应用于已爬网的源

{
  "sourceId": "6790abc1234567890def1234",
  "tags": ["support", "faq", "billing"]
}

示例：将检索标签应用于索引文档

{
  "docId": "6790abc1234567890def1235",
  "tags": ["support", "faq"]
}

______________________________________________________________________

🛡️ 安全说明

• 从不 在共享配置中对API密钥进行硬编码。更喜欢客户端秘密存储。
• 使用 最小权限 关键和考虑 排外主义者/利率限制 在您的Ethora后端。
• 在生产使用中定期轮换凭据。

CI安全扫描（仅报告）

此repo运行 仅报告 推送/PR扫描：

• gitleaks 用于秘密扫描
• 语义扫描 对于基本SAST

______________________________________________________________________

🧰 发展

克隆并在本地运行：

git clone https://github.com/dappros/ethora-mcp-server.git
cd ethora-mcp-server
npm install
npm run build
npm start

建议脚本（如果没有）：

{
  "scripts": {
    "build": "tsc -p .",
    "start": "node dist/index.js",
    "dev": "tsx src/index.ts"
  }
}

______________________________________________________________________

❓ 故障排除

• 客户端无法连接：确保 npx @ethora/mcp-server 在本地运行，没有错误。检查节点≥18。
• 身份验证错误：验证 ETHORA_BASE_URL 并且在客户端的环境中设置任何所需的秘密。
• 缺少工具：重新启动MCP客户端并检查服务器日志中的注册错误。
• 网络：确认从IDE到Ethora主机的出站访问。

______________________________________________________________________

🔗 相关转载

• Ethora聊天组件 --我们的React聊天组件用于小部件和独立应用程序

https://github.com/dappros/ethora-chat-component

• Ethora WP插件 --WordPress集成\

https://github.com/dappros/ethora-wp-plugin

• RAG演示 --RAG AI助手示例\

https://github.com/dappros/rag_demos

______________________________________________________________________

📜 许可证

看 许可证.