1. 为什么要把 MCP Server 塞进 DockerMCP Server 说白了就是一个跑在本地、通过 stdin/stdout 跟 MCP Client 对话的控制台程序。用 Node.js 写的话平时node dist/index.js就能跑起来看起来没必要折腾容器。但只要你把服务发给别人用问题就来了对方机器上 Node 版本不对、缺 Python、缺 Go、缺某个系统库报错五花八门。容器化 MCP Server 解决的就是这个「环境一致性」问题——把 Node.js 运行时、依赖、甚至它要调用的其他语言工具链全部封进镜像用户只需要装一个 Docker 就能跑。我试过把同一个 MCP Server 分别用裸 Node 和 Docker 发给同事裸 Node 那边折腾了半小时环境Docker 这边一条docker run就通了。所以这篇就聚焦 Node.js 版 MCP Server 的容器化落地从零写 Dockerfile、构建镜像、挂载配置再通过 TaoToken 的统一 Key/API 通道把模型请求接上最后用一次真实请求验证容器里的服务确实活着。适合谁看已经写过一个能跑的 Node.js MCP Server、想把它打包分发的开发者或者刚接触 MCP、想直接拿一个容器化模板改吧改吧就用的人。下面所有命令和配置都可以直接复制改掉路径和 Key 就能跑。2. TaoToken 前置拿到统一 Key 和 API 通道容器里的 MCP Server 要调模型得有个稳定的入口。TaoToken 提供统一的 Key 和 API 通道Node.js 服务里只要读环境变量就能接上不用在镜像里硬编码任何凭证——这点对容器化特别重要镜像可以随便分发Key 通过运行时注入。先去控制台建一个 API Key控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteKey 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite建好之后你会拿到一串 Key先记下来等会儿用-e注入容器。API 基地址是https://taotoken.net/api这个地址在 Node.js 代码里作为baseURL使用。如果你还没写过 MCP Server想先看看模型对话长什么样可以打开模型对话页试一句模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite接入文档在这里里面有各语言 SDK 的 baseURL 写法Node.js 部分直接对照着改接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite注意Key 只通过环境变量TAOTOKEN_API_KEY传进容器绝对不要写进 Dockerfile 或提交到 Git。镜像里只放代码和依赖凭证在docker run时注入。3. 可复制配置Dockerfile 与 config.toml 骨架3.1 项目结构假设你的 Node.js MCP Server 目录长这样入口是dist/index.jsTypeScript 编译产物mcp-server-demo/ ├── src/ │ └── index.ts ├── package.json ├── tsconfig.json └── Dockerfile3.2 多阶段 Dockerfile用 multi-stage builds构建阶段装全部依赖并编译运行阶段只留生产依赖和产物镜像能小一大截。下面这份可以直接复制# Stage 1: Builder FROM node:lts-alpine AS builder WORKDIR /app # 先拷依赖清单利用层缓存 COPY package*.json ./ RUN npm install --ignore-scripts # 再拷源码并编译 COPY . . RUN npm run build # Stage 2: Runtime FROM node:lts-alpine WORKDIR /app # 如果 MCP Server 需要调用其他语言在这里装 RUN apk add --no-cache python3 # 只拷生产依赖清单和编译产物 COPY package*.json ./ RUN npm install --production --ignore-scripts COPY --frombuilder /app/dist ./dist # 非 root 用户运行 RUN adduser -D mcpuser USER mcpuser # MCP Server 通过 stdio 通信必须保持前台运行 CMD [node, ./dist/index.js]几个关键点解释一下。--ignore-scripts是防止依赖的 postinstall 脚本在构建时干奇怪的事容器里更可控。运行阶段单独npm install --production而不是从 builder 拷node_modules是因为 builder 里可能混了 devDependencies直接拷会让镜像变大。CMD用数组形式、不加-d因为 MCP 靠 stdin/stdout 通信进程必须在前台。3.3 构建镜像在项目根目录执行docker build -t mcp-server-demo:0.1.0 .构建完看一眼大小docker images mcp-server-demo:0.1.0正常在 150MB 上下如果超过 300MB多半是node_modules拷多了或者基础镜像选错了。3.4 config.toml 骨架MCP Client 侧用 config.toml 描述怎么启动这个容器。把下面这段填进你的客户端配置路径按实际改[mcp] inputs [] [mcp.servers.mcp-server-demo] command docker args [ run, --rm, -i, -e, TAOTOKEN_API_KEY${TAOTOKEN_API_KEY}, -e, TAOTOKEN_BASE_URLhttps://taotoken.net/api, mcp-server-demo:0.1.0 ]--rm让容器退出后自动清理-i保持 stdin 打开——这两个对 stdio 型 MCP Server 是必须的。-e把宿主机的环境变量透传进容器Key 不落盘。3.5 Node.js 侧读取环境变量服务代码里这样接 TaoTokenconst baseURL process.env.TAOTOKEN_BASE_URL || https://taotoken.net/api; const apiKey process.env.TAOTOKEN_API_KEY; if (!apiKey) { console.error(TAOTOKEN_API_KEY is not set); process.exit(1); } // 后续用 baseURL apiKey 初始化你的模型客户端4. 验证请求确认容器里的服务真的通了4.1 先单独跑容器不接 MCP Client先手动跑一次确认容器能启动、能读到 Keydocker run --rm -i \ -e TAOTOKEN_API_KEY你的Key \ -e TAOTOKEN_BASE_URLhttps://taotoken.net/api \ mcp-server-demo:0.1.0如果服务启动后往 stdout 打了一行「server ready」之类的日志说明容器本身没问题。按 CtrlC 退出。4.2 用 MCP 协议发一次请求MCP 走的是 JSON-RPC over stdio可以手动喂一条初始化消息验证。新建一个init.json{jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:test,version:1.0}}}然后管道进去cat init.json | docker run --rm -i \ -e TAOTOKEN_API_KEY你的Key \ -e TAOTOKEN_BASE_URLhttps://taotoken.net/api \ mcp-server-demo:0.1.0正常会返回一段 JSON里面带serverInfo和capabilities。看到这个返回就说明容器化的 MCP Server 已经能正常握手了。4.3 接上 TaoToken 跑一次真实模型调用如果你的 MCP Server 里有个 tool 会调模型用 MCP Client 连上后触发那个 tool。观察容器日志里有没有打到https://taotoken.net/api的请求以及返回是否正常。到这一步整条链路——Docker 容器 → Node.js 服务 → TaoToken 统一通道 → 模型——就全通了。如果你打算长期跑编码类或 Agent 类任务反复手动docker run比较烦可以看下 Coding Plan它把这类长期调用的额度管理做得更省事Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite5. 本篇常见错排查5.1 容器启动后立刻退出最常见的原因是CMD写成了后台运行或者服务启动后没保持前台。检查 Dockerfile 最后一行是不是CMD [node, ./dist/index.js]不要加或nohup。另外确认dist/index.js真的存在——如果npm run build失败但构建没报错运行阶段就会找不到入口。5.2 报「TAOTOKEN_API_KEY is not set」说明环境变量没传进容器。检查docker run命令里有没有-e TAOTOKEN_API_KEY...或者 config.toml 里的-e参数有没有写对。用${TAOTOKEN_API_KEY}这种写法时要确保宿主机上这个变量真的存在可以先echo $TAOTOKEN_API_KEY确认。5.3 镜像构建时 npm install 卡住或失败多半是网络问题。可以在 Dockerfile 里换 npm 源或者构建时加--build-arg传代理配置。另外npm install --ignore-scripts有时会因为某个依赖必须跑 postinstall 而失败这种情况把--ignore-scripts去掉再试但要留意构建日志里脚本干了什么。5.4 MCP Client 连不上容器先确认-i参数在。stdio 型 MCP Server 没有-i的话 stdin 是关的握手直接失败。其次确认--rm没跟-d混用。如果 Client 报超时手动用 4.2 的管道方式测一次能通说明是 Client 配置问题不通说明是容器问题。5.5 容器里调模型报 401Key 无效或没传对。去 API Keys 页面确认 Key 还有效然后检查TAOTOKEN_BASE_URL是不是https://taotoken.net/api注意结尾不要多加斜杠。如果代码里拼接路径时重复了/api也会 404。6. 把容器化 MCP Server 接进你的工作流容器化 MCP Server 的价值不在「技术炫技」而在分发。你写好的 Node.js 服务别人docker pull一下就能用不用管 Node 版本、不用装依赖、不用配环境。配合 TaoToken 的统一 Key 和 API 通道凭证通过环境变量注入镜像本身可以公开分发而不泄露任何东西。下一步可以做的把镜像推到镜像仓库在 config.toml 里把mcp-server-demo:0.1.0换成远程 tag或者用 Coding Plan 管理长期编码任务的额度省得每次手动传 Key。接入过程中遇到报错先回到第 5 节对照排查大部分问题都在环境变量和-i参数上。
1. 为什么要把 MCP Server 塞进 DockerMCP Server 说白了就是一个跑在本地、通过 stdin/stdout 跟 MCP Client 对话的控制台程序。用 Node.js 写的话平时node dist/index.js就能跑起来看起来没必要折腾容器。但只要你把服务发给别人用问题就来了对方机器上 Node 版本不对、缺 Python、缺 Go、缺某个系统库报错五花八门。容器化 MCP Server 解决的就是这个「环境一致性」问题——把 Node.js 运行时、依赖、甚至它要调用的其他语言工具链全部封进镜像用户只需要装一个 Docker 就能跑。我试过把同一个 MCP Server 分别用裸 Node 和 Docker 发给同事裸 Node 那边折腾了半小时环境Docker 这边一条docker run就通了。所以这篇就聚焦 Node.js 版 MCP Server 的容器化落地从零写 Dockerfile、构建镜像、挂载配置再通过 TaoToken 的统一 Key/API 通道把模型请求接上最后用一次真实请求验证容器里的服务确实活着。适合谁看已经写过一个能跑的 Node.js MCP Server、想把它打包分发的开发者或者刚接触 MCP、想直接拿一个容器化模板改吧改吧就用的人。下面所有命令和配置都可以直接复制改掉路径和 Key 就能跑。2. TaoToken 前置拿到统一 Key 和 API 通道容器里的 MCP Server 要调模型得有个稳定的入口。TaoToken 提供统一的 Key 和 API 通道Node.js 服务里只要读环境变量就能接上不用在镜像里硬编码任何凭证——这点对容器化特别重要镜像可以随便分发Key 通过运行时注入。先去控制台建一个 API Key控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteKey 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite建好之后你会拿到一串 Key先记下来等会儿用-e注入容器。API 基地址是https://taotoken.net/api这个地址在 Node.js 代码里作为baseURL使用。如果你还没写过 MCP Server想先看看模型对话长什么样可以打开模型对话页试一句模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite接入文档在这里里面有各语言 SDK 的 baseURL 写法Node.js 部分直接对照着改接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite注意Key 只通过环境变量TAOTOKEN_API_KEY传进容器绝对不要写进 Dockerfile 或提交到 Git。镜像里只放代码和依赖凭证在docker run时注入。3. 可复制配置Dockerfile 与 config.toml 骨架3.1 项目结构假设你的 Node.js MCP Server 目录长这样入口是dist/index.jsTypeScript 编译产物mcp-server-demo/ ├── src/ │ └── index.ts ├── package.json ├── tsconfig.json └── Dockerfile3.2 多阶段 Dockerfile用 multi-stage builds构建阶段装全部依赖并编译运行阶段只留生产依赖和产物镜像能小一大截。下面这份可以直接复制# Stage 1: Builder FROM node:lts-alpine AS builder WORKDIR /app # 先拷依赖清单利用层缓存 COPY package*.json ./ RUN npm install --ignore-scripts # 再拷源码并编译 COPY . . RUN npm run build # Stage 2: Runtime FROM node:lts-alpine WORKDIR /app # 如果 MCP Server 需要调用其他语言在这里装 RUN apk add --no-cache python3 # 只拷生产依赖清单和编译产物 COPY package*.json ./ RUN npm install --production --ignore-scripts COPY --frombuilder /app/dist ./dist # 非 root 用户运行 RUN adduser -D mcpuser USER mcpuser # MCP Server 通过 stdio 通信必须保持前台运行 CMD [node, ./dist/index.js]几个关键点解释一下。--ignore-scripts是防止依赖的 postinstall 脚本在构建时干奇怪的事容器里更可控。运行阶段单独npm install --production而不是从 builder 拷node_modules是因为 builder 里可能混了 devDependencies直接拷会让镜像变大。CMD用数组形式、不加-d因为 MCP 靠 stdin/stdout 通信进程必须在前台。3.3 构建镜像在项目根目录执行docker build -t mcp-server-demo:0.1.0 .构建完看一眼大小docker images mcp-server-demo:0.1.0正常在 150MB 上下如果超过 300MB多半是node_modules拷多了或者基础镜像选错了。3.4 config.toml 骨架MCP Client 侧用 config.toml 描述怎么启动这个容器。把下面这段填进你的客户端配置路径按实际改[mcp] inputs [] [mcp.servers.mcp-server-demo] command docker args [ run, --rm, -i, -e, TAOTOKEN_API_KEY${TAOTOKEN_API_KEY}, -e, TAOTOKEN_BASE_URLhttps://taotoken.net/api, mcp-server-demo:0.1.0 ]--rm让容器退出后自动清理-i保持 stdin 打开——这两个对 stdio 型 MCP Server 是必须的。-e把宿主机的环境变量透传进容器Key 不落盘。3.5 Node.js 侧读取环境变量服务代码里这样接 TaoTokenconst baseURL process.env.TAOTOKEN_BASE_URL || https://taotoken.net/api; const apiKey process.env.TAOTOKEN_API_KEY; if (!apiKey) { console.error(TAOTOKEN_API_KEY is not set); process.exit(1); } // 后续用 baseURL apiKey 初始化你的模型客户端4. 验证请求确认容器里的服务真的通了4.1 先单独跑容器不接 MCP Client先手动跑一次确认容器能启动、能读到 Keydocker run --rm -i \ -e TAOTOKEN_API_KEY你的Key \ -e TAOTOKEN_BASE_URLhttps://taotoken.net/api \ mcp-server-demo:0.1.0如果服务启动后往 stdout 打了一行「server ready」之类的日志说明容器本身没问题。按 CtrlC 退出。4.2 用 MCP 协议发一次请求MCP 走的是 JSON-RPC over stdio可以手动喂一条初始化消息验证。新建一个init.json{jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:test,version:1.0}}}然后管道进去cat init.json | docker run --rm -i \ -e TAOTOKEN_API_KEY你的Key \ -e TAOTOKEN_BASE_URLhttps://taotoken.net/api \ mcp-server-demo:0.1.0正常会返回一段 JSON里面带serverInfo和capabilities。看到这个返回就说明容器化的 MCP Server 已经能正常握手了。4.3 接上 TaoToken 跑一次真实模型调用如果你的 MCP Server 里有个 tool 会调模型用 MCP Client 连上后触发那个 tool。观察容器日志里有没有打到https://taotoken.net/api的请求以及返回是否正常。到这一步整条链路——Docker 容器 → Node.js 服务 → TaoToken 统一通道 → 模型——就全通了。如果你打算长期跑编码类或 Agent 类任务反复手动docker run比较烦可以看下 Coding Plan它把这类长期调用的额度管理做得更省事Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite5. 本篇常见错排查5.1 容器启动后立刻退出最常见的原因是CMD写成了后台运行或者服务启动后没保持前台。检查 Dockerfile 最后一行是不是CMD [node, ./dist/index.js]不要加或nohup。另外确认dist/index.js真的存在——如果npm run build失败但构建没报错运行阶段就会找不到入口。5.2 报「TAOTOKEN_API_KEY is not set」说明环境变量没传进容器。检查docker run命令里有没有-e TAOTOKEN_API_KEY...或者 config.toml 里的-e参数有没有写对。用${TAOTOKEN_API_KEY}这种写法时要确保宿主机上这个变量真的存在可以先echo $TAOTOKEN_API_KEY确认。5.3 镜像构建时 npm install 卡住或失败多半是网络问题。可以在 Dockerfile 里换 npm 源或者构建时加--build-arg传代理配置。另外npm install --ignore-scripts有时会因为某个依赖必须跑 postinstall 而失败这种情况把--ignore-scripts去掉再试但要留意构建日志里脚本干了什么。5.4 MCP Client 连不上容器先确认-i参数在。stdio 型 MCP Server 没有-i的话 stdin 是关的握手直接失败。其次确认--rm没跟-d混用。如果 Client 报超时手动用 4.2 的管道方式测一次能通说明是 Client 配置问题不通说明是容器问题。5.5 容器里调模型报 401Key 无效或没传对。去 API Keys 页面确认 Key 还有效然后检查TAOTOKEN_BASE_URL是不是https://taotoken.net/api注意结尾不要多加斜杠。如果代码里拼接路径时重复了/api也会 404。6. 把容器化 MCP Server 接进你的工作流容器化 MCP Server 的价值不在「技术炫技」而在分发。你写好的 Node.js 服务别人docker pull一下就能用不用管 Node 版本、不用装依赖、不用配环境。配合 TaoToken 的统一 Key 和 API 通道凭证通过环境变量注入镜像本身可以公开分发而不泄露任何东西。下一步可以做的把镜像推到镜像仓库在 config.toml 里把mcp-server-demo:0.1.0换成远程 tag或者用 Coding Plan 管理长期编码任务的额度省得每次手动传 Key。接入过程中遇到报错先回到第 5 节对照排查大部分问题都在环境变量和-i参数上。
