dingtalk-workspace-mcp

A protocol bridge that turns DingTalk's official dws CLI into a host-agnostic MCP server. 把钉钉官方 dws CLI 转成任意 MCP host 可用的通用 MCP server。

English · 简体中文 · Roadmap · Comparison

📦 Install

There is only one way to install this package — via npx, invoked by your MCP host. Everything else on this page is either an alternative form of the same command or a separate upstream dependency.

npm package: @sputnicyoji/dingtalk-workspace-mcp

One-liner — verify the package can be pulled

npx -y @sputnicyoji/dingtalk-workspace-mcp --version

Copy, paste, run. If it prints a version number, npm and Node are working and the package is reachable. (You'll see a dws not found error on first run if dws isn't installed yet — that's fine; see Prerequisites.)

Wire it into your MCP host

Paste this block into mcp.json (or your host's equivalent — Claude Desktop, Cursor, Codex, any MCP host):

{
  "mcpServers": {
    "dingtalk": {
      "command": "npx",
      "args": ["-y", "@sputnicyoji/dingtalk-workspace-mcp"]
    }
  }
}

Restart the host. ~80 dingtalk.* tools appear automatically. No npm install -g, no clone, no build — npx pulls the package on first run and caches it.

mcp_servers:
  dingtalk:
    command: "npx"
    args: ["-y", "@sputnicyoji/dingtalk-workspace-mcp"]
    timeout: 180

"args": ["-y", "@sputnicyoji/dingtalk-workspace-mcp@0.0.5"]

[!NOTE] No tokens, no env vars, no secrets in the host config. Identity, permissions and token refresh are entirely delegated to the dws CLI.

Prerequisites

These are separate from installing this package — they are the upstream tools the package needs at runtime.

Install dws once per machine:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.ps1 | iex

# then authenticate (one-time browser OAuth)
dws auth login

CLI flags

-v, --verbose         enable verbose logging to stderr
    --timeout <sec>   per-tool-call timeout (default 120, env DINGTALK_MCP_TIMEOUT)
    --version         print version
-h, --help            show help

English

Why this exists

DingTalk already ships dws as the official capability engine. This project does not replace it. On startup it walks the dws --help tree (or dws schema --format json when authenticated) and translates the entire dws command surface into MCP tools. When dws ships a new product or capability, restart the server — zero code change required.

Direct dws ... calls work for terminals and scripts. MCP hosts need something different: tool discovery, structured arguments, standard errors, permission boundaries, and a way to avoid handing arbitrary shell access to an LLM. This server provides exactly that layer — and nothing more.

One-line differentiation

Moat: DingTalk's strategy is the official dws CLI plus a broader MCP ecosystem, not a single first-party MCP server that replaces third-party adapters. This project stays ecosystem-neutral: one dws-driven adapter, any MCP host, no host-specific glue code.

Architecture

Any MCP host (Claude Desktop / Cursor / Codex / ...)
        │
        │ MCP tools/call (stdio JSON-RPC)
        ▼
packages/dingtalk-workspace-mcp/
    stateless  ·  dynamic schema  ·  host-agnostic
        │
        │ child_process.spawn
        ▼
    dws binary (user-installed, on PATH)
        │
        │ HTTPS
        ▼
    DingTalk Open Platform

Invariants:

• Stateless — each tool call spawns dws fresh; no business state held in-process
• Zero business assumptions — no product-specific parsers, no embedded report templates, no alert rules
• Zero host assumptions — no host-specific branches anywhere in the code path

Behavior summary

Status

Published: @sputnicyoji/dingtalk-workspace-mcp@0.0.5

Out of scope

• Rewriting dws (the Go version is officially maintained — don't reinvent the wheel)
• Other IM platforms (Feishu / Slack / Teams / WeChat)
• Business logic in the main package (report templates, identity resolution, alert rules)
• Host-specific optimizations of any kind (would break host-agnostic guarantees)
• Token management (entirely delegated to dws)

Documentation

• CLAUDE.md — agent working instructions and project constraints
• docs/ARCHITECTURE.md — authoritative architecture and design decisions
• docs/ROADMAP.md — version cadence
• docs/COMPARISON.md — differentiation vs alternative implementations

简体中文

📦 安装

本包只有一种安装方式——通过 MCP host 调起的 npx。这一节里其他代码块要么是同一条命令的不同形态，要么是上游依赖的安装命令，不是替代方案。

npm 包名：@sputnicyoji/dingtalk-workspace-mcp

一行命令验证拉得到包

npx -y @sputnicyoji/dingtalk-workspace-mcp --version

复制粘贴运行。能打印版本号就说明 npm 和 Node 都正常、包能拉到。（如果还没装 dws，首次运行会报 dws not found，正常，看下面前置依赖。）

接入 MCP host

把以下配置贴到 mcp.json（Claude Desktop / Cursor / Codex 等等都用这同一份）：

{
  "mcpServers": {
    "dingtalk": {
      "command": "npx",
      "args": ["-y", "@sputnicyoji/dingtalk-workspace-mcp"]
    }
  }
}

重启 host 后约 80 个 dingtalk.* tool 自动出现。不用 npm install -g、不用克隆、不用编译——npx 首次运行时拉包并缓存。

mcp_servers:
  dingtalk:
    command: "npx"
    args: ["-y", "@sputnicyoji/dingtalk-workspace-mcp"]
    timeout: 180

"args": ["-y", "@sputnicyoji/dingtalk-workspace-mcp@0.0.5"]

[!NOTE] host 配置里没有 token、没有环境变量、没有任何密钥。身份、权限、token 刷新全部委托给 dws CLI。

前置依赖

这些和"安装本包"是两回事——是本包运行时需要的上游工具。

dws 每台机器装一次：

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.ps1 | iex

# 完成 OAuth 登录（一次性浏览器授权）
dws auth login

为什么需要这一层

钉钉已经有官方能力底座 dws。本项目不替代 dws，只把 dws 转成通用 MCP server：启动时遍历 dws --help 树（已认证时优先 dws schema --format json），把 dws 整个命令面动态翻译成 MCP tools。dws 升级新增能力，重启一次 MCP server 即生效，零代码维护。

直接调用 dws ... 适合终端和脚本。MCP host 需要的是另一层：工具发现、结构化参数、标准错误、权限边界，以及避免把任意 shell 权限交给 LLM。本项目只提供这层，不接管钉钉身份、权限和业务语义。

一句话差异化

护城河：钉钉的策略是官方 dws CLI 加 MCP 生态，而不是用一个官方全覆盖 MCP server 替代第三方适配器。本项目保持生态中立：一个 dws-driven adapter，任意 MCP host 可接，不写 host 专用胶水。

架构不变量

• 无状态：每次 tool call 独立 spawn dws，进程内不持久化任何业务数据
• 零业务假设：不解析"哪个产品"、不内嵌报告模板、不做告警规则
• 零 host 假设：代码路径里不出现 if <某个 host> 分支

身份 / 权限 / token 全部由 dws 承担，本项目只做 CLI <-> MCP 的无状态翻译。

不做什么

• 重写 dws（Go 版官方维护，不重造轮子）
• 扩展到飞书 / Slack / Teams / 微信（单仓单平台，保持聚焦）
• 在主包放业务逻辑（报告模板、身份解析、告警规则）
• 任何形式的 host 专用优化（破坏 host-agnostic 原则）
• 自己管 token（全部委托 dws）

文档索引

• CLAUDE.md — agent 工作指令与项目约束
• docs/ARCHITECTURE.md — 权威架构与设计决策
• docs/ROADMAP.md — 版本节奏
• docs/COMPARISON.md — 差异化对比

MIT © Yoji