diff --git a/README.md b/README.md
index 12f34f9e..566bcd53 100644
--- a/README.md
+++ b/README.md
@@ -26,7 +26,7 @@
- ✅ **长期记忆：** 自动将对话记忆持久化至本地文件和数据库中，包括核心记忆、日级记忆和梦境蒸馏，支持关键词及向量检索
- ✅ **个人知识库：** 自动整理结构化知识，通过交叉引用构建知识图谱，支持通过对话管理和可视化浏览知识库
- ✅ **技能系统：** Skills 安装和运行的引擎，支持从 [Skill Hub](https://skills.cowagent.ai/)、GitHub 等一键安装技能，或通过对话创造 Skills
-- ✅ **工具系统：** 内置文件读写、终端执行、浏览器操作、定时任务等工具，Agent 自主调用以完成复杂任务
+- ✅ **工具系统：** 内置文件读写、终端执行、浏览器操作、定时任务等工具，支持 MCP 协议，通过 Agent 自主调用完成复杂任务
- ✅ **CLI系统：** 提供终端命令和对话命令，支持进程管理、技能安装、配置修改等操作
- ✅ **多模态消息：** 支持对文本、图片、语音、文件等多类型消息进行解析、处理、生成、发送等操作
- ✅ **多模型支持：** 支持 DeepSeek、MiniMax、Claude、Gemini、OpenAI、GLM、Qwen、Doubao、Kimi 等国内外主流模型厂商
diff --git a/docs/docs.json b/docs/docs.json
index 3b236a1a..3eebadb0 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -120,6 +120,12 @@
"tools/vision",
"tools/browser"
]
+ },
+ {
+ "group": "MCP 工具",
+ "pages": [
+ "tools/mcp"
+ ]
}
]
},
@@ -307,6 +313,12 @@
"en/tools/vision",
"en/tools/browser"
]
+ },
+ {
+ "group": "MCP Tools",
+ "pages": [
+ "en/tools/mcp"
+ ]
}
]
},
@@ -494,6 +506,12 @@
"ja/tools/vision",
"ja/tools/browser"
]
+ },
+ {
+ "group": "MCP Tool",
+ "pages": [
+ "ja/tools/mcp"
+ ]
}
]
},
diff --git a/docs/en/tools/index.mdx b/docs/en/tools/index.mdx
index 694c7cf2..b85930e8 100644
--- a/docs/en/tools/index.mdx
+++ b/docs/en/tools/index.mdx
@@ -48,3 +48,13 @@ The following tools require additional dependencies or API key configuration:
Search the internet for real-time information
+
+## MCP Tools
+
+Integrate thousands of community tools (maps, GitHub, Notion, etc.) via the [Model Context Protocol](https://modelcontextprotocol.io). Configure `mcp.json` once, ready to use:
+
+
+
+ Supports standard stdio / SSE transports. Hot-reload, zero code changes.
+
+
diff --git a/docs/en/tools/mcp.mdx b/docs/en/tools/mcp.mdx
new file mode 100644
index 00000000..9978c46e
--- /dev/null
+++ b/docs/en/tools/mcp.mdx
@@ -0,0 +1,109 @@
+---
+title: MCP Tools
+description: Integrate external tool ecosystems via the Model Context Protocol
+---
+
+CowAgent supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), allowing the Agent to directly invoke tens of thousands of community MCP tools. Configure `mcp.json` once and the tools are exposed to the LLM in exactly the same way as built-in tools — automatically selected and invoked.
+
+## Configuration File
+
+CowAgent reads `~/cow/mcp.json`. If the file does not exist, no MCP tools are loaded — and no error is raised.
+
+For Docker deployments, the official `docker-compose.yml` already mounts the host's `./cow` directory to `/home/agent/cow` inside the container (i.e. the container user's `~/cow`). Just drop `mcp.json` into the host's `./cow/` directory and it will take effect.
+
+### Standard Format
+
+Fully compatible with the MCP community standard, identical to Claude Desktop / Cursor:
+
+```json
+{
+ "mcpServers": {
+ "": {
+ "command": "npx",
+ "args": ["-y", "some-mcp-package"],
+ "env": {
+ "API_KEY": "your-key-here"
+ }
+ }
+ }
+}
+```
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `command` | stdio | Executable to launch the server (e.g. `npx`, `python`, `uvx`) |
+| `args` | No | Arguments passed to `command` |
+| `env` | No | Environment variables for the subprocess, commonly used for API keys |
+| `url` | SSE | SSE endpoint URL (alternative to `command`) |
+| `disabled` | No | When `true`, this server is skipped — handy for temporary disabling |
+
+### Full Example
+
+```json
+{
+ "mcpServers": {
+ "fetch": {
+ "command": "uvx",
+ "args": ["mcp-server-fetch"]
+ },
+ "github": {
+ "command": "npx",
+ "args": ["-y", "@modelcontextprotocol/server-github"],
+ "env": {
+ "GITHUB_PERSONAL_ACCESS_TOKEN": ""
+ }
+ }
+ }
+}
+```
+
+- **fetch**: Generic web page fetcher that returns page text content. No API key required.
+- **github**: Access GitHub repos, issues, PRs, etc. Requires a Personal Access Token.
+
+## Let the Agent Configure It for You
+
+CowAgent ships with `read` / `write` / `edit` tools, so **you can simply send the MCP config to the Agent and ask it to write the file**:
+
+For example:
+
+```markdown
+Add this MCP to ~/cow/mcp.json:
+
+{"mcpServers":{"fetch":{"command":"uvx","args":["mcp-server-fetch"]}}}
+```
+
+The Agent will:
+
+1. Read the existing MCP config and merge the new server entry, preserving existing ones
+2. Hot-reload the new MCP server, so the corresponding tools become available on the next message
+
+## How It Works
+
+- **Async loading at startup**: All servers configured in `mcp.json` are loaded asynchronously in the background, never blocking the main loop — chat is usable immediately.
+- **Hot reload**: When you or the Agent modifies `mcp.json`, changed servers are automatically reloaded after the current message — no need to restart cow.
+- **Flat exposure**: Each method exposed by an MCP server appears as an individual tool. The LLM picks one directly without a second-stage decision.
+
+## Supported Transports
+
+| Transport | Description | Config Field |
+| --- | --- | --- |
+| **stdio** | Subprocess communication. The most common option, with the richest community ecosystem. | `command` + `args` |
+| **SSE** | HTTP Server-Sent Events, suitable for remotely hosted MCP services. | `url` |
+
+## Troubleshooting
+
+| Symptom | What to Check |
+| --- | --- |
+| Agent has no MCP tools after startup | Verify that `~/cow/mcp.json` exists and contains valid JSON |
+| A specific server fails to load | Look for `[MCP] Server 'xxx' load failed` in startup logs — usually missing dependencies or API keys |
+| Changes to `mcp.json` aren't applied | Changes take effect on **the next message**. If the server config didn't actually change (e.g. only comments edited), no restart is triggered |
+| Docker deployment | Make sure host's `./cow` is mounted to `/home/agent/cow` in the container, then just drop `mcp.json` into host's `./cow/`. Or just ask the Agent to do it |
+
+## Recommended MCP Marketplaces
+
+You can browse third-party MCP marketplaces and copy a JSON config to use directly, for example:
+
+- [mcp.so](https://mcp.so) — Global MCP service index
+- [ModelScope MCP Hub](https://modelscope.cn/mcp) — ModelScope's MCP hub, more reliable from mainland China
+
+Any MCP server that follows the standard protocol (stdio / SSE) integrates with CowAgent out of the box.
diff --git a/docs/ja/tools/index.mdx b/docs/ja/tools/index.mdx
index baa27fff..7b2b068c 100644
--- a/docs/ja/tools/index.mdx
+++ b/docs/ja/tools/index.mdx
@@ -48,3 +48,13 @@ Toolは、AgentがOSリソースにアクセスするための中核機能です
インターネットからリアルタイム情報を検索
+
+## MCP Tool
+
+[Model Context Protocol](https://modelcontextprotocol.io) を介して、コミュニティの既製 Tool（地図、GitHub、Notion など数千種類）を統合できます。`mcp.json` を一度設定するだけで利用可能です：
+
+
+
+ 標準の stdio / SSE トランスポートをサポート。ホットリロードで、コード変更不要
+
+
diff --git a/docs/ja/tools/mcp.mdx b/docs/ja/tools/mcp.mdx
new file mode 100644
index 00000000..e450a099
--- /dev/null
+++ b/docs/ja/tools/mcp.mdx
@@ -0,0 +1,109 @@
+---
+title: MCP Tool
+description: Model Context Protocol を介して外部Toolエコシステムを統合
+---
+
+CowAgent は [Model Context Protocol (MCP)](https://modelcontextprotocol.io) をサポートしており、コミュニティで提供されている数万種類の MCP Tool を Agent から直接呼び出せます。`mcp.json` を一度設定すれば、組み込みToolとまったく同じ形で LLM に公開され、自動的に選択・呼び出されます。
+
+## 設定ファイル
+
+CowAgent は `~/cow/mcp.json` を読み込みます。ファイルが存在しない場合は MCP Tool は読み込まれず、エラーにもなりません。
+
+Docker デプロイの場合、公式の `docker-compose.yml` はホスト側の `./cow` をコンテナ内の `/home/agent/cow`（コンテナユーザーの `~/cow`）にマウント済みです。ホスト側の `./cow/` に `mcp.json` を置くだけで反映されます。
+
+### 標準フォーマット
+
+MCP コミュニティ標準に完全準拠しており、Claude Desktop / Cursor と同じです：
+
+```json
+{
+ "mcpServers": {
+ "": {
+ "command": "npx",
+ "args": ["-y", "some-mcp-package"],
+ "env": {
+ "API_KEY": "your-key-here"
+ }
+ }
+ }
+}
+```
+
+| フィールド | 必須 | 説明 |
+| --- | --- | --- |
+| `command` | stdio | サーバーを起動する実行コマンド（`npx`、`python`、`uvx` など） |
+| `args` | 任意 | `command` に渡す引数 |
+| `env` | 任意 | サブプロセスの環境変数。API Key などに利用 |
+| `url` | SSE | SSE エンドポイントの URL（`command` と二者択一） |
+| `disabled` | 任意 | `true` のとき該当サーバーをスキップ。一時的に無効化したいときに便利 |
+
+### 完全な例
+
+```json
+{
+ "mcpServers": {
+ "fetch": {
+ "command": "uvx",
+ "args": ["mcp-server-fetch"]
+ },
+ "github": {
+ "command": "npx",
+ "args": ["-y", "@modelcontextprotocol/server-github"],
+ "env": {
+ "GITHUB_PERSONAL_ACCESS_TOKEN": ""
+ }
+ }
+ }
+}
+```
+
+- **fetch**：汎用 Web ページ取得。ページ本文を返す。API Key 不要
+- **github**：GitHub のリポジトリ、Issue、PR などにアクセス。Personal Access Token が必要
+
+## Agent に設定を任せる
+
+CowAgent には `read` / `write` / `edit` Tool が組み込まれているため、**MCP の設定をそのまま Agent に渡して、ファイルに書き込んでもらえます**：
+
+例：
+
+```markdown
+この MCP を ~/cow/mcp.json に追加してください：
+
+{"mcpServers":{"fetch":{"command":"uvx","args":["mcp-server-fetch"]}}}
+```
+
+Agent は次のように動作します：
+
+1. 既存の MCP 設定ファイルを読み込み、新しい server エントリをマージ（既存の項目は保持）
+2. 増分の MCP Server を自動でリロードし、次のメッセージから対応する Tool が利用可能に
+
+## 動作の仕組み
+
+- **起動時の非同期ロード**：`mcp.json` に設定された全 server はバックグラウンドで非同期に読み込まれ、メインループをブロックしません。会話はすぐに開始できます
+- **ホットリロード**：ユーザーまたは Agent が `mcp.json` を変更すると、メッセージ処理完了時に変更された server のみが自動でリロードされます。cow の再起動は不要です
+- **フラットな公開**：MCP server が公開する各メソッドは独立した Tool として並列に公開され、LLM が直接選択して呼び出します。二段階の判断は不要です
+
+## サポートされるトランスポート
+
+| トランスポート | 説明 | 設定フィールド |
+| --- | --- | --- |
+| **stdio** | サブプロセス通信。最も一般的で、コミュニティのエコシステムが最も豊富 | `command` + `args` |
+| **SSE** | HTTP Server-Sent Events。リモートホスト型の MCP サービス向け | `url` |
+
+## トラブルシューティング
+
+| 症状 | 確認ポイント |
+| --- | --- |
+| 起動後に MCP Tool が一つもない | `~/cow/mcp.json` が存在し、JSON が正しいか確認 |
+| 特定の server が読み込みに失敗する | 起動ログの `[MCP] Server 'xxx' load failed` を確認。多くは依存関係の不足や API Key 未設定 |
+| `mcp.json` の変更が反映されない | 変更は **次のメッセージ** から有効になる。server の設定が実質的に変わっていない（コメントだけ変更など）場合は再起動されない |
+| Docker デプロイ | ホストの `./cow` がコンテナ内の `/home/agent/cow` にマウントされていることを確認し、ホスト側の `./cow/` に `mcp.json` を配置。または Agent に直接インストールを依頼 |
+
+## おすすめ MCP マーケットプレイス
+
+各種サードパーティのマーケットプレイスから既製の MCP server を探し、JSON 設定をコピーしてそのまま利用できます。例：
+
+- [mcp.so](https://mcp.so) — グローバル MCP サービスインデックス
+- [ModelScope MCP 広場](https://modelscope.cn/mcp) — 魔搭コミュニティの MCP 広場、中国本土からのアクセスが安定
+
+MCP 標準プロトコル（stdio / SSE）に準拠していれば、コードを一切変更せずに CowAgent に統合できます。
diff --git a/docs/tools/index.mdx b/docs/tools/index.mdx
index dcd0a986..0d96923a 100644
--- a/docs/tools/index.mdx
+++ b/docs/tools/index.mdx
@@ -57,3 +57,13 @@ description: CowAgent 内置工具系统
控制浏览器访问和操作网页
+
+## MCP 工具
+
+通过 [Model Context Protocol](https://modelcontextprotocol.io) 接入社区生态中的各种MCP工具，配置一次 `mcp.json` 即用即得：
+
+
+
+ 支持 stdio / SSE 标准协议，热更新，零代码接入
+
+
diff --git a/docs/tools/mcp.mdx b/docs/tools/mcp.mdx
new file mode 100644
index 00000000..0973f25a
--- /dev/null
+++ b/docs/tools/mcp.mdx
@@ -0,0 +1,109 @@
+---
+title: MCP 工具
+description: 通过 Model Context Protocol 接入外部工具生态
+---
+
+CowAgent 支持 [Model Context Protocol (MCP)](https://modelcontextprotocol.io)，让 Agent 能够直接调用社区中数以万计的 MCP 工具。配置一次 `mcp.json`，工具就会以与内置工具完全相同的方式呈现给 LLM，可被自动选择和调用。
+
+## 配置文件
+
+CowAgent 读取 `~/cow/mcp.json`。文件不存在时不会启用任何 MCP 工具，也不会报错。
+
+Docker 部署时，官方 `docker-compose.yml` 已经把宿主机 `./cow` 挂载到容器内 `/home/agent/cow`（即容器用户的 `~/cow`），把 `mcp.json` 放进宿主机 `./cow/` 目录即可生效。
+
+### 标准格式
+
+完全兼容 MCP 社区标准，同 Claude Desktop / Cursor 一致：
+
+```json
+{
+ "mcpServers": {
+ "": {
+ "command": "npx",
+ "args": ["-y", "some-mcp-package"],
+ "env": {
+ "API_KEY": "your-key-here"
+ }
+ }
+ }
+}
+```
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `command` | stdio | 启动 server 的可执行命令（如 `npx`、`python`、`uvx`） |
+| `args` | 否 | 传给 command 的参数列表 |
+| `env` | 否 | 子进程的环境变量，常用于 API Key |
+| `url` | SSE | SSE 端点 URL（与 `command` 二选一） |
+| `disabled` | 否 | `true` 时跳过该 server，便于临时关闭 |
+
+### 完整示例
+
+```json
+{
+ "mcpServers": {
+ "fetch": {
+ "command": "uvx",
+ "args": ["mcp-server-fetch"]
+ },
+ "github": {
+ "command": "npx",
+ "args": ["-y", "@modelcontextprotocol/server-github"],
+ "env": {
+ "GITHUB_PERSONAL_ACCESS_TOKEN": ""
+ }
+ }
+ }
+}
+```
+
+- **fetch**：通用网页抓取，返回页面文本内容，无需 API Key
+- **github**：访问 GitHub 仓库、Issue、PR 等，需要 Personal Access Token
+
+## 让 Agent 帮你配置
+
+CowAgent 自带 `read` / `write` / `edit` 工具，**直接把要装的 MCP 配置发给 Agent，让它写到配置文件中：
+
+例如：
+
+```markdown
+帮我把这个 MCP 加到 ~/cow/mcp.json 里：
+
+{"mcpServers":{"fetch":{"command":"uvx","args":["mcp-server-fetch"]}}}
+```
+
+Agent 会：
+
+1. 访问 MCP 配置文件，合并新 server 配置，保留已有项
+2. 自动重载增量的 MCP Server，下一次对话即可使用相应 Tools
+
+## 工作方式
+
+- 启动时**异步加载**：`mcp.json` 中配置的所有 server 会在后台异步加载，不阻塞主流程，对话可以立刻使用
+- **热更新**：用户或 Agent 修改 `mcp.json` 后，消息处理完成时会自动重载变更的 server，无需重启 cow
+- **平铺呈现**：每个 MCP server 暴露的多个方法会平铺为独立的工具，LLM 直接选择调用，不需要二次决策
+
+## 支持的传输协议
+
+| 协议 | 说明 | 配置字段 |
+| --- | --- | --- |
+| **stdio** | 子进程通信，最常见，社区生态最丰富 | `command` + `args` |
+| **SSE** | HTTP Server-Sent Events，适合远程托管的 MCP 服务 | `url` |
+
+## 排错
+
+| 现象 | 排查方向 |
+| --- | --- |
+| 启动后 Agent 没有 MCP 工具 | 检查 `~/cow/mcp.json` 是否存在、JSON 格式是否合法 |
+| 某个 server 加载失败 | 查看启动日志中的 `[MCP] Server 'xxx' load failed`，常见为依赖未装、API Key 缺失 |
+| 修改 `mcp.json` 没有生效 | 改动会在**下一条消息**生效；若 server 配置不变（如只改注释），不会触发重启 |
+| Docker 部署 | 确认宿主机 `./cow` 已挂载到容器内 `/home/agent/cow`，`mcp.json` 直接放进宿主机 `./cow/` 目录即可，或者直接对话 Agent 安装 |
+
+## MCP 市场推荐
+
+可以从各个第三方广场寻找现成的 MCP server，复制 JSON 配置即可使用，例如：
+
+- [mcp.so](https://mcp.so) — 全球 MCP 服务索引
+- [ModelScope MCP 广场](https://modelscope.cn/mcp) — 魔搭社区 MCP 广场，国内访问更稳定
+
+只要遵循 MCP 标准协议（stdio / SSE），都可以直接接入 CowAgent。