cn-free-ai-mcp

国内直连的免费 AI 能力 MCP 服务器：文本对话、图片生成、语音识别、语音合成——四合一、零成本、clone 即用。 Zero-cost, China-accessible AI MCP server: chat, image generation, speech-to-text & text-to-speech — four free AI capabilities in one, works out of the box.

中文文档

✨ 功能特性

全部能力实测可用：npm test 13/13 通过（含真实端到端调用）。

Related MCP server: minimax-omni

🧠 API 选型（为什么这样选）

本项目调用两个国内直连、无需科学上网的免费服务：

1. 智谱开放平台（bigmodel.cn）— 文本 / 图片 / 语音识别

• 选型理由：一个平台同时提供文本、图像、语音三类免费模型，API 统一（OpenAI 兼容、Bearer 认证），国内直连速度快。

• Base URL：https://open.bigmodel.cn/api

• 免费模型（本项目默认值）：

• 认证：Authorization: Bearer <API_KEY>，Key 在 bigmodel.cn 控制台 免费创建。

• 接口（本项目内部调用）：POST /paas/v4/chat/completions、POST /paas/v4/images/generations、POST /paas/v4/audio/transcriptions

2. 微软 Edge TTS — 语音合成

• 选型理由：智谱 glm-tts 收费；Edge TTS 完全免费、无需 API Key、中文音色丰富（晓晓/云希等），适合开源项目零成本落地。

• 调用方式：npm 包 node-edge-tts（微软 Edge 在线 TTS），输出 mp3。

• 切换收费后端：text_to_speech 支持 provider: "zhipu" 切换回智谱 glm-tts（输出 wav）。

🚀 快速开始（下载即可用）

环境要求：Node.js ≥ 18 + 一个 MCP 客户端（Claude Code / Reasonix 等）。

git clone https://github.com/<你的用户名>/cn-free-ai-mcp.git
cd cn-free-ai-mcp
npm install
cp .env.example .env    # Windows: copy .env.example .env

编辑 .env 填入智谱 Key（免费获取）：

ZHIPU_API_KEY=你的key

没有 Key 也能跑：text_to_speech 默认走免费的 Edge TTS；配置 Key 后 4 个能力全部可用。

注册 MCP（自带 .mcp.json，Claude Code 规范，Reasonix 兼容，相对路径通用）：

{
  "mcpServers": {
    "zhipu-ai": {
      "command": "node",
      "args": ["./src/index.js"],
      "cwd": ".",
      "env": { "ZHIPU_API_KEY": "${ZHIPU_API_KEY}" }
    }
  }
}

${ZHIPU_API_KEY} 运行时从环境变量 / 项目 .env 展开，密钥不写入配置文件。重启客户端后工具以 mcp__zhipu-ai__<tool> 暴露。

🔧 工具与调用示例

音色参考：Edge TTS（默认）zh-CN-XiaoxiaoNeural（晓晓）、zh-CN-YunxiNeural（云希）、en-US-AriaNeural 等；智谱（provider:"zhipu"）tongtong/chuichui/xiaochen/jam/kazi/douji/luodo。

📦 项目结构

cn-free-ai-mcp/
├── .mcp.json           # MCP 注册声明（相对路径，通用）
├── .env.example        # 环境变量模板（复制为 .env 使用）
├── package.json
├── src/index.js        # MCP server（4 个工具）
└── test/               # 测试（离线 + 真实端到端）

🔒 安全设计

• 密钥不入库：.env 已被 .gitignore 忽略，配置只用 ${VAR} 占位展开

• SSRF 防护：音频 URL 仅允许 https、拒绝重定向与内网/回环/链路本地地址

• 输入校验：本地音频限 .wav/.mp3 且 ≤25MB；TTS 写盘前校验音频文件头

• 错误净化：上游错误信息截断、折叠空白，避免回显敏感内容

• 无注入面：无 shell 调用、无动态执行

🧪 测试

npm test

离线用例（握手、防护）无需任何 Key / 网络；检测到 .env 有真实 Key 时自动执行真实端到端用例（对话、图片生成、语音识别、Edge TTS 合成→ASR 识别闭环）。当前基线：13/13 通过，0 skip。

🤝 贡献

欢迎 Issue / PR。开发前请确保 npm test 全绿。

📄 许可证

MIT

English

✨ Features

All capabilities verified end-to-end: npm test 13/13 passing (including real API calls).

🧠 Why these APIs

Two China-direct, no-VPN free services:

1. Zhipu AI (open.bigmodel.cn) — chat / image / ASR in one platform, OpenAI-compatible, Bearer auth. Free models: glm-4.7-flash (chat), cogview-3-flash (image), glm-asr-2512 (ASR). Base URL: https://open.bigmodel.cn/api.

2. Microsoft Edge TTS — free, no API key, rich Chinese voices (Xiaoxiao/Yunxi...), via npm node-edge-tts. Optional paid fallback: provider: "zhipu" (Zhipu glm-tts).

🚀 Quick Start

git clone https://github.com/<you>/cn-free-ai-mcp.git
cd cn-free-ai-mcp
npm install
cp .env.example .env    # fill ZHIPU_API_KEY (optional but recommended)

Register the bundled .mcp.json in your MCP client (Claude Code / Reasonix), restart, and tools are exposed as mcp__zhipu-ai__<tool>. Works without a key too — TTS defaults to free Edge TTS.

🔧 Tools

chat (prompt/system/temperature/max_tokens), generate_image (prompt/size/quality), transcribe_audio (audio path or https URL), text_to_speech (text/provider/voice/output_path/speed/volume).

🔒 Security

.env git-ignored (keys never committed, ${VAR} placeholders only); SSRF-guarded (https-only, no redirects/internal IPs); input validation (.wav/.mp3 ≤25MB, TTS file-header checks); error sanitization; no shell injection surface.

🧪 Testing

npm test — offline cases need no key/network; with a real key in .env, end-to-end cases run automatically (chat, image, ASR, Edge-TTS→ASR loop). Baseline: 13/13, 0 skipped.

📄 License

MIT