Labsco
dappros logo

Ethora MCP CLI

★ 6

from dappros

Chat & messaging SDK and cloud platform for your apps. Supports AI agents and RAG bots.

🔥🔥🔥✓ VerifiedPaid serviceNeeds API keys
#email#automation#payments#scraping#documents#git#security

Ethora MCP Server (Model Context Protocol)

npm Node License

Add to Cursor Install in VS Code Install in VS Code Insiders

One-click install for Cursor and VS Code (buttons above). For Claude Code, Claude Desktop, GitHub Copilot, Gemini CLI, Codex CLI, Windsurf, and Cline, see Using with MCP Clients below.

An MCP (Model Context Protocol) CLI/server that connects popular MCP clients to the Ethora platform — an open-source chat & messaging platform with a built-in AI agent / chatbot framework. This runs locally on a developer machine via stdio rather than as a hosted Ethora service.
Use it from Cursor, VS Code MCP, Claude Desktop, or Windsurf/Cline to manage apps and chat rooms, broadcast messages, deploy AI agents / chatbots with RAG sources, and automate B2B provisioning workflows. (ERC-20 wallet tools are also included — see the tool list below.)

Part of the Ethora SDK ecosystem — see all SDKs, tools, and sample apps. Follow cross-SDK updates in the Release Notes.

✨ What you get

  • Talk to the Ethora platform directly from your IDE or AI agent client (Cursor, VS Code MCP, Claude Desktop, Windsurf / Cline).
  • Both user-auth flows (login/register, files, owner/admin endpoints) and B2B / app-token flows (tenant provisioning, broadcast jobs, async user batches, AI bot config).
  • Built-in recipes, prompts, and generators for the most common Ethora workflows (Vite/Next chat-component setup, B2B bootstrap, AI-bot enablement, RAG sources).
  • Standard tool response envelope ({ ok, ts, meta, data | error }) so agent code can reason about success/failure consistently.

🧱 Standard response envelope (tools)

All tools return JSON in a consistent envelope:

  • Success: { ok: true, ts, meta, data }
  • Error: { ok: false, ts, meta, error }, where error includes:
    • code: stable string (prefer API code, otherwise inferred)
    • httpStatus: HTTP status when the failure came from an API call
    • requestId: request/correlation id if returned by API
    • hint: 1-line “what to do next”

🚀 Using with MCP Clients

Every client runs the same thing — npx -y @ethora/mcp-server over stdio. One-click buttons exist for Cursor and VS Code (top of this README). For the rest it's a short config block or a one-line command.

Cursor

Use the Add to Cursor button above, or manually: Settings → MCP → Add new global MCP server:

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

VS Code (and GitHub Copilot)

Use the Install in VS Code button above, or add a .vscode/mcp.json file (project-level) — note the key is servers:

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

GitHub Copilot's agent mode in VS Code reads this same .vscode/mcp.json — no separate setup. (For a user-level install instead, put the servers block under "mcp" in your User Settings JSON.)

Claude Code

One command:

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

Add --scope user to make it available in every project. Verify with claude mcp list.

To pre-configure credentials, pass them as env vars with -e (recommended over the ethora-configure tool — see note below):

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

Secrets note: prefer env vars (above) or your MCP client's secret store for credentials. The ethora-configure tool also works, but it passes secrets as tool arguments, which means they end up in the conversation transcript. Use it for quick local testing, not for tokens you care about.

Claude Desktop

Settings → Developer → Edit Config, open claude_desktop_config.json:

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

Gemini CLI

Add to ~/.gemini/settings.json (global) or .gemini/settings.json (per project):

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

Codex CLI

Add to ~/.codex/config.toml — note the table name is mcp_servers (underscore; mcp-servers is silently ignored):

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

Windsurf

Settings → Cascade → MCP Servers → View raw config (~/.codeium/windsurf/mcp_config.json):

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

Cline

Open the MCP servers panel and edit cline_mcp_settings.json:

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

🧪 Quick test

After the server shows as connected in your client:

  • Run list tools (client command) to verify Ethora tools are available.
  • Check config/connectivity: call ethora-doctor (or ethora-status)
  • For a first local/manual test:
    • call ethora-configure with apiUrl / appJwt
    • call ethora-auth-use-user
    • call ethora-user-login
    • then try ethora-app-list or ethora-wallet-get-balance
  • For a server-side/B2B test:
    • call ethora-configure with apiUrl / b2bToken
    • call ethora-auth-use-b2b
    • then try ethora-b2b-app-create or ethora-app-tokens-list-v2

🤖 App automation loop

Once you already have an app selected with appToken auth:

  • call ethora-auth-use-app
  • call ethora-bot-get-v2 to inspect current bot status and prompt settings
  • call ethora-sources-site-list-v2 and ethora-sources-docs-list-v2 to inspect indexed sources
  • call ethora-sources-site-tags-update-v2 or ethora-sources-docs-tags-update-v2 to organize retrieval by tags
  • call ethora-chats-message-v2 / ethora-chats-history-v2 if your backend exposes the chat automation surface on the same API host

Example: apply retrieval tags to a crawled source

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

Example: apply retrieval tags to an indexed document

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

🛡️ Security notes

  • Never hardcode API keys in shared config. Prefer client-side secret stores.
  • Use least privilege keys and consider allowlists/rate limits on your Ethora backend.
  • Rotate credentials regularly in production use.

CI security scans (report-only)

This repo runs report-only scans on pushes/PRs:

  • gitleaks for secret scanning
  • semgrep for basic SAST

🧰 Development

Clone and run locally:

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

Suggested scripts (if not present):

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

🔗 Related Repos

📜 License

See LICENSE.