Choose your path
Zhin serves two kinds of people. Pick yours — the rest of this README is split the same way.
Potencialize seu agente
O comando do próprio publicador. Não é um endpoint do PlugMCP.
Host a copy with our keys and logs.
npx -y @zhin.js/[email protected]O Claude Code não tem link de instalação para um comando local. Copie o comando abaixo e execute-o em um terminal.
claude mcp add zhin.js-mcp -- npx -y @zhin.js/mcp@1.1.31Execute em um terminal.
{ "mcpServers": { "zhin.js-mcp": { "command": "npx", "args": [ "-y", "@zhin.js/[email protected]" ] } }}claude_desktop_config.json
URL remota ou um comando na sua máquina? Como as duas instalações diferem
Rodar no PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDo publicador
Zhin serves two kinds of people. Pick yours — the rest of this README is split the same way.
Model Context Protocol (MCP) service for Zhin.js - AI assistant integration
| 🛠 Developer — plugin & adapter authors |
|---|
| You are | A group owner, community operator or support lead. You run the bot; you don't write TypeScript. | Someone who writes commands, plugins, AI tools or platform adapters. |
| You use | The browser Console and a config file | TypeScript, create-zhin-app, the zhin CLI |
| You get | Welcomes, check-ins, reminders, feed pushes, moderation, announcements that wait for approval, a one-switch emergency stop | One codebase on 20+ platforms, a feature is a file, hot reload that can't take you down |
| Start here | Try the live demo → Operator & Group Admin Guide | Developer quick start → First plugin |
Zhin.js is a framework for bots that live in chat apps — operators run them from a browser console, developers build them in TypeScript. Think community bots, personal assistants, notification and support bots, AI chat assistants.
commands/hello/index.ts is the /hello command. Middleware, message cards, scheduled jobs and AI tools work the same way — no registration boilerplate.Zhin is not an in-editor coding agent (like Cursor or Claude Code). Its AI features exist to power bots on chat platforms.
You don't need to write code to run a Zhin bot well. Once a developer (or your ops person) has deployed it once, day-to-day work happens in the browser.
Connect. Open console.zhin.dev and enter the bot's API address and token (HTTP_TOKEN). Use a read-only Demo token for colleagues who only watch. Not deployed yet? Try the live demo first.
Group ops with guardrails. The AI can draft announcements but only a person with approval rights can send them; risky admin actions such as kicking a member become approval cards with a cooldown; every decision is traceable in decision replay.
When to call a developer: first deployment or server moves, a feature no existing plugin provides, a new platform, connecting the AI to your business systems, or errors in the run log you can't interpret.
👉 Full guide: Operator & Group Admin Guide · Console path · Troubleshooting
Everything below is for people writing plugins and adapters in TypeScript.
No platform account and no model key required.
npm create zhin-app my-bot -y
cd my-bot
pnpm dev
http://127.0.0.1:8068) and the HTTP_TOKEN from .env./hello. You should get a reply.-y accepts every default: a browser Sandbox (simulated chat) instead of a real platform, and no AI. Requirements: Node.js ≥22.19.0 and pnpm 9+. Something wrong? Run npx zhin doctor.
Full walkthrough: Quick start · Prefer not to install yet? Try the live demo.
[!IMPORTANT] Upgrading an existing bot from 1.1.13 or earlier? The Runtime now only accepts
configVersion: 2. Stop the Bot first, upgradezhin.js/@zhin.js/clito the latest, then runzhin migrate instances(preview) andzhin migrate instances --apply(backs up first). Full steps and restore: Upgrading to configVersion 2.
chat platform your project (a plugin) chat platform
QQ / Discord … ──▶ Adapter ──▶ Middleware ──▶ Command ──────────────▶ Adapter ──▶ reply
│ no command matched
└──▶ AI Agent (optional) ──▶ Tools
New to these terms? Read Core concepts at a glance — it explains every word the docs use, in plain language.
A whole bot can be one file:
// bot.ts
import { definePlugin } from 'zhin.js'
import { defineCommand } from 'zhin.js/command'
export default definePlugin({
name: 'my-bot',
setup({ addCommand }) {
addCommand('hello', defineCommand({
description: 'Say hello',
execute: () => 'Hello from Zhin!',
}))
},
})
As it grows, move each capability into its own file. The folder path is the name, and the file registers itself:
// commands/remind/index.ts → /remind 10 stretch
import { defineCommand } from 'zhin.js/command'
export default defineCommand({
description: 'Create a reminder',
params: {
minutes: { type: 'integer', min: 1, max: 1440 },
note: { type: 'text', default: 'Take a break' },
},
options: { quiet: { type: 'boolean', default: false } }, // --quiet
execute: ({ params, options }) =>
options.quiet ? 'OK' : `OK, I'll remind you in ${params.minutes} min: ${params.note}`,
})
my-bot/
├── package.json # "zhin" field: entry and child plugins (what is installed)
├── zhin.config.yml # port, platform credentials, models (how it is configured)
├── .env # secrets: HTTP_TOKEN, API keys
├── plugin.ts # entry: definePlugin()
├── commands/ # /commands — folder path = command name
├── middlewares/ # runs on every message
├── components/ # reusable JSX message cards
├── schedules/ # scheduled jobs
├── tools/ # functions the AI may call (optional)
└── pages/ # custom Console pages
npx zhin setup --adapters # pick platforms, enter credentials
pnpm install && pnpm dev
Each adapter has a maturity tier (Stable / Advanced / Experimental) and its own setup guide: Adapters overview.
npx zhin setup --ai # choose a provider (OpenAI, Ollama, …) and write the config
pnpm install && pnpm dev
The wizard installs the Agent runtime and the tool / prompt features, and writes something like this to zhin.config.yml (keys go to .env):
ai:
enabled: true
providers:
openai-main:
sdk: openai
apiKey: ${AI_API_KEY}
agents:
zhin:
provider: openai-main
model: gpt-4o-mini
Messages that match no command now go to the model — in DMs by default, in groups with an ai: prefix or a mention. Give it abilities by adding files to tools/; permissions, approvals and file/network access are enforced by framework policy, not by the prompt.
Detailed table and sizes: Install tiers. Since 1.1, ZhinAgent / AIService are imported from zhin.js/agent / zhin.js/ai, not from zhin.js.
Operators & group owners
Developers
Full site: zhin.js.org (Chinese by default; switch language in the nav).
npx zhin setup # add platforms, AI, database to an existing project
npx zhin doctor # diagnose Node, ports, tokens, manifest
npx @zhin.js/cli new my-plugin --standalone # scaffold a publishable plugin package
npx zhin search <keyword> # find community plugins
npx zhin install <name> # install and mount a plugin
All commands: CLI reference.
How the layers fit together: architecture · repo structure.
git clone https://github.com/zhinjs/zhin.git
cd zhin
pnpm install && pnpm build
pnpm dev # runs examples/minimal-bot
Other entry points: pnpm --filter single-file-bot dev (one-file bot) and pnpm dev:test (maintainers' kitchen-sink test-bot, not a template). See the contributing guide for checks, conventions and the release flow.
Model Context Protocol (MCP) service for Zhin.js - AI assistant integration
{ "mcpServers": { "zhin.js-mcp": { "command": "npx", "args": [ "-y", "@zhin.js/[email protected]" ] } }}Ferramentas
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Este registro não lista nenhuma variável de ambiente obrigatória.
@zhin.js/mcp roda localmente via stdio.
Última verificação: 2026-11-16. Model Context Protocol (MCP) service for Zhin.js - AI assistant integration