一、简介

智虾助手 是一款基于 MCP（Model Context Protocol）协议的轻量级智能助理。它可以充当你的私人助理、编程助手、写作助手，安装非常简单——一条命令 + 一个配置即可搞定。

⚡

小巧轻量
单一可执行文件，无需安装运行时

🔌

多 MCP Server
内置 filesystem / time / skill，支持扩展

🤖

任意 OpenAI 格式模型
兼容 DeepSeek、GLM、Qwen 等

🖥️

多终端并发
命令行控制台 + Web + 飞书 + 微信ClawBot + QQBot 机器人同时运行

📝

灵活提示词
内联配置或文件引用系统提示词

🌐

网页浏览
通过 Playwright MCP 浏览网页、查天气

软件截图

图片识别

推送天气

查询新闻

二、软件下载

提供各平台预编译二进制，下载后直接运行，无需安装任何依赖。

操作系统	架构	下载链接
Windows	x86_64	mcp-agent-windows-amd64.exe
macOS	x86_64 (Intel)	mcp-agent-darwin-amd64
macOS	ARM64 (Apple Silicon)	mcp-agent-darwin-arm64
Linux	x86_64	mcp-agent-linux-amd64
Linux	ARM64	mcp-agent-linux-arm64

Windows 推荐使用 PowerShell 或 Git Bash 运行。macOS / Linux 下载后需执行 chmod +x mcp-agent-* 赋予执行权限。

三、快速开始

下载

选择对应平台
的可执行文件

配置

创建 mcp-agent.toml
填写 API Key 与模型

运行

终端执行一条命令
即可开始对话

扩展

添加更多 MCP Server
解锁更多能力

编写最小配置文件 mcp-agent.toml，仅启用 web 终端 + time MCP Server，配合本地 Ollama 模型，几分钟即可跑起来体验。

1. 准备模型服务

最简单的方式是使用本地 Ollama：

ollama pull qwen3.5

也可使用任何兼容 OpenAI API 的在线服务（DeepSeek、Qwen、GLM 等），见下文 5.1 LLM 配置。

2. 编写最小配置

在工作目录下创建 mcp-agent.toml：

# ===== 最小快速入门配置 =====
# 仅包含：本地 LLM + web 终端 + time MCP Server

[llm]
# 本地 Ollama（默认值，可省略）
base_url = "http://127.0.0.1:11434/v1"
api_key  = "sk-your-secret-key"
model    = "qwen3.5"
stream   = true

[prompt]
system = """
你是用户的私人助理，请按用户指示进行回复，语言尽可能精简。
"""

[mcp]
[[mcp.servers]]
name        = "time"
description = "获取当前时间时区,查看设置定时任务等"
endpoint    = "time --with-timer"

[[terminals]]
type = "web"
host = "127.0.0.1"
port = 8088

3. 启动程序

./mcp-agent --config-file /path/to/mcp-agent.toml

看到类似下面的日志即表示启动成功：

[INFO] Loaded config from: mcp-agent.toml
[INFO] Initializing Findea MCP Agent v1.0.3 ...
[INFO]   API Base URL: http://127.0.0.1:11434/v1
[INFO]   Model: qwen3.5
[INFO]   MCP Servers: time
[OK]   Fetched N tools from 1 MCP servers
[INFO] Terminal: web

4. 开始对话

浏览器打开 http://127.0.0.1:8088，即可与 Agent 对话。试试问它：

「现在几点了？」—— 会调用 time MCP Server 获取当前时间
「5 分钟后提醒我喝水」—— 会设置一个定时任务

上面的配置只用了 time 一个内置 MCP Server。程序还内置了 filesystem、skill、subagent、memory、 command、git、nodejs 等 Server，并支持远程 HTTP/SSE Server 与 stdio 子进程。完整能力请继续阅读下文。

四、参数说明

参数获取优先级：命令行参数 > 配置文件 > 环境变量 > 默认值

参数	说明	环境变量
`--base-url`	OpenAI API 基础 URL	`OPENAI_BASE_URL`
`--api-key`	OpenAI API 密钥	`OPENAI_API_KEY`
`--model`	AI 模型名称	`AI_MODEL`
`--config-file`	TOML 配置文件路径（默认：`mcp-agent.toml`）	无
`--mode`	运行模式：`agent`（默认）或 `hub`	无
`--hub-transport`	Hub 传输方式：`stdio`（默认）或 `http`	无
`--hub-address`	Hub HTTP 模式监听地址（默认：`127.0.0.1:8080`）	无
`--verbose`	启用详细工具调用日志	无
`--version`	显示版本信息	无
`--help`	显示帮助信息	无

五、配置文件

MCP Server、系统提示词、终端类型等高级配置均通过 TOML 配置文件管理。

配置文件查找顺序：

--config-file 指定的路径
当前目录下的 mcp-agent.toml
~/.mcp-agent/mcp-agent.toml

配置文件所在目录会被记为 ConfigDir，用于解析内置 MCP Server 的默认数据目录（如 skills、memory、agents 子目录），优先于全局 ~/.mcp-agent/。

配置文件包含以下顶层节（section），均为可选：

[agent]        # Agent 身份信息（可选）
[llm]          # 大语言模型配置（可选）
[prompt]       # 系统提示词配置（可选）
[mcp]          # MCP Server 配置（可选）
[[terminals]]  # 终端配置（可多个，数组）

5.1 Agent 身份信息

用于标识当前 Agent，主要影响终端标题显示和子智能体（subagent）的描述。

字段	类型	说明
`name`	string	Agent 名称，会作为终端标题前缀
`description`	string	Agent 描述，用于子智能体介绍

[agent]
name        = "my-assistant"
description = "我的私人编程助手"

5.2 LLM 配置

支持任何兼容 OpenAI 格式的大模型，包括 DeepSeek-V3、Qwen、GPT-4o 等在线服务，也可通过 Ollama 在本地运行开源模型。

字段	类型	默认值	说明
`base_url`	string	`http://127.0.0.1:11434/v1`	API 基础 URL
`api_key`	string	`-`	API 密钥；本地模型（如 Ollama）可用 `"-"`
`model`	string	`qwen3.5`	模型名称
`vision`	bool	`false`	是否启用视觉（图片）能力
`stream`	bool	`false`	是否启用流式响应
`temperature`	float	`0.0`	采样温度，省略则使用 API 默认值
`auto_compact_threshold`	int	`102400`	对话历史自动压缩阈值（字节），超过则触发压缩
`max_iterations`	int	`10`	单轮对话中工具调用的最大迭代次数，超过会暂停并询问用户
`retry_count`	int	`0`	LLM 调用失败重试次数：`0`=不重试，`-1`=无限重试，`>0`=重试 N 次（指数退避）

[llm]

# OpenAI
# base_url = "https://api.openai.com/v1"
# api_key  = "sk-xxx"
# model    = "gpt-4o"

# Ollama（本地部署）
base_url = "http://127.0.0.1:11434/v1"  # 默认值，适用于本地 Ollama
api_key  = "-"                           # 本地模型可使用 "-"
model    = "qwen3.5"

# 高级选项
vision                 = false
stream                 = true
temperature            = 0.7
auto_compact_threshold = 102400   # 100KB
max_iterations         = 15
retry_count            = 3

使用 Ollama 本地部署：先下载 Ollama，再执行 ollama pull qwen3.5 拉取模型。

5.3 系统提示词

系统提示词用于设定 Agent 的角色和行为准则。支持三种方式，优先级从高到低：

内联提示词（system 字段）
文件加载（file 字段）
自动回退：配置文件同目录下的 PROMPT.md

[prompt]

# 内联提示词（优先于文件）
system = """
你是用户的私人助理，请按用户指示进行回复，语言尽可能精简。
调用危险工具（如:删除）一定要请示用户，得到肯定后才执行。
当你要完成复杂任务，请先拆解成几个子任务，分而治之。
"""

# 或从文件加载
# file = "system-prompt.txt"

若 [prompt] 节未配置或 system 和 file 均为空，程序会自动读取 ConfigDir/PROMPT.md 作为系统提示词。

六、终端配置

终端定义了 Agent 与用户交互的渠道。支持配置多个终端并发运行，每个终端拥有独立的会话（共享同一个 MCP 客户端）。若未配置任何终端，默认启用一个 console 终端。

6.1 命令行终端（默认）

[[terminals]]
type = "console"

6.2 Web 浏览器终端

通过 WebSocket 提供浏览器交互界面。

字段	类型	默认值	说明
`host`	string	`127.0.0.1`	监听地址
`port`	int	`8088`	监听端口
`base_url`	string	-	对外访问基础 URL

[[terminals]]
type    = "web"
host    = "127.0.0.1"
port    = 8088

6.3 微信ClawBot

需 node 执行 weixin-clawbot-toml.js，获取配置。

字段	TOML 键名	说明
BaseURL	`base_url`	微信 API 网关地址（默认 `https://ilinkai.weixin.qq.com`）
CDNBaseURL	`cdn_base_url`	CDN 图片下载地址（默认 `https://novac2c.cdn.weixin.qq.com/c2c`）
BotToken	`bot_token`	登录后获得的 bot_token
BotID	`ilink_bot_id`	ilink_bot_id
IlinkUserID	`ilink_user_id`	可选，仅响应此用户

# 微信ClawBot终端
# 下载 https://findea.cn/mcp-agent/static/example/weixin/weixin-clawbot-toml.js 
# node weixin/weixin-clawbot-toml.js

[[terminals]]
type          = "weixin"
base_url      = "https://ilinkai.weixin.qq.com"
bot_token     = "xxx@im.bot:xxx"
ilink_bot_id  = "xx@im.bot"
ilink_user_id = "xxxk@im.wechat"   # 可选

6.4 飞书机器人

需申请飞书应用，获取 app_id 和 app_secret。

字段	类型	说明
`app_id`	string	飞书应用 App ID
`app_secret`	string	飞书应用 App Secret
`user_open_id`	string	可选，限定仅响应特定用户

[[terminals]]
type         = "feishu"
app_id       = "cli_xxxxxxxxxx"
app_secret   = "your_app_secret"
user_open_id = "ou_xxxxxxxxxx"   # 可选，限定特定用户

飞书应用需开启以 im: 开头的消息相关权限，事件配置选择长连接，并订阅 im.message.receive_v1 等消息事件。

6.5 QQ 机器人

字段	TOML 键名	说明
AppID	`app_id`	QQ 机器人 AppID
AppSecret	`app_secret`	QQ 机器人 AppSecret
UserOpenID	`user_open_id`	可选，仅响应此 C2C 用户
GroupID	`group_id`	可选，仅响应此群
MediaProxyURL	`media_proxy_url`	可选，媒体下载代理，如 `socks5://127.0.0.1:1080`

[[terminals]]
type            = "qq"
app_id          = "your_app_id"
app_secret      = "your_app_secret"
user_open_id    = "ou_xxx"              # 可选
group_id        = "group_xxx"           # 可选
media_proxy_url = "socks5://127.0.0.1:1080"  # 可选

6.6 多终端并发

可同时配置多个终端，它们会并发运行。当 console 终端退出时，其他终端也会停止。

[[terminals]]
type = "console"

[[terminals]]
type         = "feishu"
app_id       = "cli_xxx"
app_secret   = "xxx"

七、MCP Server 配置

通过 [[mcp.servers]] 数组定义多个 MCP Server。内置 MCP Server 有：filesystem、time、skill、subagent、 memory、command、git、nodejs。

字段	类型	说明
`name`	string	Server 名称（为空时使用 endpoint）
`description`	string	人类可读的描述，会注入到系统提示词中供模型参考
`endpoint`	string	Server 端点：内置名称 / 可执行命令 / HTTP(S) URL / `sse <url>`
`args`	[]string	额外参数（与 endpoint 中内嵌的参数合并）
`env`	map[string]string	子进程环境变量（仅对 stdio 子进程生效）
`allowed_tools`	[]string	工具白名单：非空时仅暴露这些工具
`denied_tools`	[]string	工具黑名单：这些工具始终被排除（优先级高于白名单）

7.1 endpoint 类型说明

endpoint 字段支持四种形式，程序自动识别：

endpoint 形式	传输方式	说明
`filesystem`、`time` 等内置名	内置实现	见下方「内置 MCP Server」
`npx -y @playwright/mcp@latest`	stdio 子进程	以命令行方式启动外部 MCP Server
`https://example.com/mcp`	Streamable HTTP	以 `http://` 或 `https://` 开头的 URL
`sse https://example.com/sse`	SSE（Server-Sent Events）	以 `sse` 前缀触发

endpoint 中可内嵌参数（空格分隔），也可用 args 单独定义，二者等价且会合并： endpoint = "filesystem D:\\data" 等价于 endpoint = "filesystem" + args = ["D:\\data"]。

📁 filesystem

文件系统读写操作，支持限定允许/拒绝的工具，可指定可访问目录

🕐 time

获取当前时间、时区信息，查看设置定时任务等

🎯 skill

技能指南，教 AI 如何完成特定任务

🤖 subagent

子智能体，适合处理目标清晰而上下文可能很长的小任务

🧠 memory

记忆存储，记录用户信息或日记，可自定义存储目录

⌨️ command

命令行执行工具（不走 shell），支持白名单/黑名单

🌿 git

支持执行各种 git 命令，可配置扫描深度与写权限

📦 nodejs

Node.js 环境，可以运行 JavaScript 代码

🌐 playwright

浏览器自动化，浏览网页、查天气、搜索新闻，需安装 Node.js

🐳 mcp-sandbox

隔离的 Docker 环境，安全运行 Node.js 代码

内置 MCP

[[mcp.servers]]
name        = "filesystem"
description = "文件系统读取操作等"
endpoint    = "filesystem"
# args = ['~', 'D:\', 'E:\']  # ~ 代表用户主目录， 默认为当前目录

[[mcp.servers]]
name        = "time"
description = "获取当前时间时区,查看设置定时任务等"
endpoint    = "time --with-timer"

[[mcp.servers]]
name        = "skill"
description = "技能指南，可以学习如何做事情"
endpoint    = "skill"
# args = ["./skills", "~/my-skills"]  # 自定义 skills 目录
# 默认：当前目录的 skills 或 ~/.mcp-agent/skills

[[mcp.servers]]
name        = "subagent"
description = "子智能体，适合处理目标清晰而上下文可能很长的小任务"
endpoint    = "subagent"
# args = []  # 自定义 agents 目录
# 默认：当前目录的 subagents 或 ~/.mcp-agent/subagents

[[mcp.servers]]
name        = "memory"
description = "记忆存储，记录用户信息或日记"
endpoint    = "memory"
# args = ['D:\my-memories']  # 自定义存储目录
# 默认：~/.mcp-agent/memory/

[[mcp.servers]]
name        = "command"
description = "命令行执行工具（不走 shell）"
endpoint    = "command --workdir=. --allow=go,git,pnpm --deny=rm,powershell"

[[mcp.servers]]
name        = "git"
description = "支持执行各种git命令"
endpoint    = "git"
args = [
    "--write-access",
    "--discover-level=1",   # 扫描深度：0=不扫描，1=一级子目录，2=二级，以此类推
    "~/data/code",          # ~ 代表用户目录，也可指定绝对路径如 D:\my-projects
]

[[mcp.servers]]
name        = "nodejs"
description = "nodejs环境，可以运行JavaScript代码"
endpoint    = "nodejs ~"   # . = 当前目录，~ = 用户主目录，或指定绝对路径

command 工具内部使用 exec.CommandContext 直接执行，不通过 shell；并阻止 sh -c、cmd /c、powershell -Command 等高风险模式，降低命令注入风险。 nodejs 需要安装 Node.js v24.14.0 LTS，建议使用 mcp-sandbox 隔离的 Docker 环境以降低安全风险。

工具过滤

通过 allowed_tools 和 denied_tools 控制每个 Server 暴露的工具：

[[mcp.servers]]
name          = "filesystem"
endpoint      = "filesystem"
allowed_tools = ["read_file", "list_directory"]  # 仅暴露这两个工具
denied_tools  = ["delete_file"]                  # 始终排除

环境变量注入

对 stdio 子进程类型的 Server，可通过 env 注入环境变量：

[[mcp.servers]]
name     = "my-server"
endpoint = "node my-mcp-server.js"
env = { API_KEY = "xxx", DEBUG = "true" }

Playwright

需要 Node.js v24.14.0 LTS 以及 Microsoft Edge 或 Firefox。

[[mcp.servers]]
name = "playwright"
description = """
常用网址：
天气 https://tianqi.qq.com/
新闻 https://www.msn.cn/zh-cn/...
搜索引擎 https://cn.bing.com/search?q=%s
"""
endpoint = "npx -y @playwright/mcp@latest --browser=msedge"
# endpoint = "npx -y @playwright/mcp@latest --browser=firefox"
# endpoint = "npx -y @playwright/mcp@latest --browser=msedge --headless"

mcp-sandbox

需要Docker安装 mcp-sandbox.zip。

[[mcp.servers]]

name="mcp-sandbox"
description="隔离的alpine linux docker环境，安装好了 nodejs(v20.15.1) npm(v10.9.1)，可以运行JavaScript代码"
endpoint="http://docker_server_ip:18080/mcp"

高德地图

申请 API Key：高德开放平台

[[mcp.servers]]
name="gaode-map"
description="高德地图服务：基础LBS服务（含路径规划、地理编码等）、基础地图定位服务和基础搜索服务"
endpoint="https://mcp.amap.com/mcp?key=xxx"

腾讯地图

申请 API Key：腾讯位置服务

[[mcp.servers]]
name="tencent-map"
description="腾讯地图服务：基础LBS服务（含路径规划、地理编码等）、基础地图定位服务和基础搜索服务"
endpoint="https://mcp.map.qq.com/mcp?key=xxx&format=0"

SSE 模式

[[mcp.servers]]
name        = "gaode-map-sse"
description = "高德地图（SSE 模式）"
endpoint    = "sse https://mcp.amap.com/sse?key=YOUR_API_KEY"

八、Hub 模式

除默认的 agent 模式外，程序还支持 hub 模式，将自身作为 MCP Server 对外提供服务（聚合所有配置的 MCP Server 的工具）。

# stdio 模式（供其他 MCP 客户端通过标准输入输出调用）
./mcp-agent --mode hub --hub-transport stdio

# HTTP 模式（监听网络端口）
./mcp-agent --mode hub --hub-transport http --hub-address 127.0.0.1:8080

Hub 模式复用同一份 mcp-agent.toml 中的 [mcp] 和 [prompt] 配置。

参数	说明
`--mode`	`agent`（默认）或 `hub`
`--hub-transport`	`stdio`（默认）或 `http`
`--hub-address`	HTTP 模式监听地址，默认 `127.0.0.1:8080`

九、完整配置示例

完整的配置文件示例请参考： mcp-agent.example.zip

# ===== Agent 身份 =====
[agent]
name        = "my-assistant"
description = "我的私人助理"

# ===== LLM 配置 =====
[llm]
base_url = "http://127.0.0.1:11434/v1"
api_key  = "-"
model    = "qwen3.5"
stream   = true
retry_count = 3

# ===== 系统提示词 =====
[prompt]
system = """
你是用户的私人助理，请按用户指示进行回复，语言尽可能精简。
调用危险工具（如:删除）一定要请示用户，得到肯定后才执行。
"""

# ===== 终端 =====
[[terminals]]
type = "console"

[[terminals]]
type    = "web"
host    = "127.0.0.1"
port    = 8088

# ===== MCP Servers =====
[[mcp.servers]]
name        = "time"
description = "获取当前时间时区,查看设置定时任务等"
endpoint    = "time --with-timer"

[[mcp.servers]]
name        = "filesystem"
description = "文件系统读取操作等"
endpoint    = "filesystem ~"

[[mcp.servers]]
name        = "skill"
description = "技能指南，可以学习如何做事情"
endpoint    = "skill"

[[mcp.servers]]
name        = "subagent"
description = "子智能体，适合处理目标清晰而上下文可能很长的小任务"
endpoint    = "subagent"

[[mcp.servers]]
name        = "memory"
description = "记忆存储，记录用户信息或日记"
endpoint    = "memory"

[[mcp.servers]]
name        = "git"
description = "支持执行各种git命令"
endpoint    = "git"
args = ["--write-access", "--discover-level=1", "~/data/code"]

[[mcp.servers]]
name        = "nodejs"
description = "nodejs环境，可以运行JavaScript代码"
endpoint    = "nodejs ~"

# 远程 MCP Server（HTTP）
[[mcp.servers]]
name        = "gaode-map"
description = "高德地图服务：路径规划、地理编码、定位、搜索等"
endpoint    = "https://mcp.amap.com/mcp?key=YOUR_API_KEY"

# stdio 子进程 MCP Server
[[mcp.servers]]
name        = "playwright"
description = "浏览器自动化"
endpoint    = "npx -y @playwright/mcp@latest --browser=msedge --headless"

智虾助手 MCP Agent