内容
# 工具列表
[](https://go.dev)
[](LICENSE)
[](https://github.com/mimichat-ai/mimi-tools/actions/workflows/go.yml)
MCP 工具服务器，使用 Go + MCP SDK 构建。提供可供 LLM 调用工具：exec（跨平台 shell 命令）、read、write、edit（支持模糊匹配）、search_name、search_content、tree。支持 Streamable HTTP/SSE/stdio 传输模式。
## 功能特点
- **exec**：使用 shell 在系统上执行命令
- **read**：读取文件内容，可选行范围
- **write**：将内容写入文件，如果需要，创建父目录
- **edit**：编辑文件，替换匹配的字符串。支持精确匹配和模糊匹配（忽略空格差异）
- **tree**：显示目录树结构
- **search_name**：在目录树中按名称模式搜索文件（支持 glob、正则表达式和子字符串匹配；默认为 glob）
- **search_content**：在文件中搜索文本内容
> ⚠️ **安全警告**
> `exec` 工具允许任意 shell 命令执行。这是按照设计（它使 LLM 代理能够构建、测试和调试代码），但这也意味着：
> - **绝不能在没有额外身份验证/授权的情况下将 HTTP/SSE 端点暴露给公共互联网**
> - **在容器中运行**（参见 Docker 部分）以隔离执行环境
> - **仅与受信任的 LLM 代理一起使用** — 恶意提示可能导致命令注入
> - 对于生产部署，通过操作系统级权限限制文件访问
## 快速开始
```bash
# 构建
go build -o mimi-tools ./cmd/mimi-tools
# 在 stdio 模式下运行（适用于 Claude Desktop 等本地 MCP 客户端）
MIMI_TRANSPORT=stdio ./mimi-tools
# 或作为 HTTP 服务器运行（默认，仅监听 localhost）
./mimi-tools
# 服务器监听 http://127.0.0.1:2333
```
> ⚠️ **裸金属安全通知**
> 默认绑定地址是 `127.0.0.1`（仅限 localhost）。`exec` 工具允许
> 任意 shell 命令执行 — 不要在共享或公共服务器上将绑定地址更改为 `0.0.0.0`
>，而无需额外的身份验证/授权。对于远程部署，使用 Docker 容器（如下所示），它通过容器边界提供
> 网络隔离。
### 与 MCP 客户端集成
配置您的 MCP 客户端（例如 Claude Desktop）以连接到 mimi-tools：
**stdio 模式** (`claude_desktop_config.json`)：
```json
{
"mcpServers": {
"mimi-tools": {
"command": "/path/to/mimi-tools",
"args": [],
"env": { "MIMI_TRANSPORT": "stdio" }
}
}
}
```
**HTTP 模式** （适用于远程客户端）：
```json
{
"mcpServers": {
"mimi-tools": {
"url": "http://localhost:2333/"
}
}
}
```
## 传输模式
mimi-tools 支持三种传输模式，由 `MIMI_TRANSPORT` 环境变量控制：
| 模式 | 环境变量 | 描述 |
|------|---------------------|-------------|
| HTTP | `MIMI_TRANSPORT=http` | 流式 HTTP（默认） |
| SSE | `MIMI_TRANSPORT=sse` | 服务器发送事件 |
| Stdio | `MIMI_TRANSPORT=stdio` | 标准输入/输出 |
### HTTP 模式（默认）
```bash
MIMI_TRANSPORT=http mimi-tools
# 或
mimi-tools # 默认 http
```
监听 `MIMI_ADDR`（默认：`127.0.0.1:2333`）。客户端向服务器发送 POST 请求。
### SSE 模式
```bash
MIMI_TRANSPORT=sse mimi-tools
```
监听 `MIMI_ADDR`（默认：`127.0.0.1:2333`）。客户端通过 GET 连接到 `/sse` 以获取服务器发送事件。
### Stdio 模式
```bash
MIMI_TRANSPORT=stdio mimi-tools
```
从 stdin 读取并写入 stdout。适用于本地 MCP 客户端集成。
## 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `MIMI_TRANSPORT` | `http` | 传输模式：`http`、`sse` 或 `stdio` |
| `MIMI_ADDR` | `127.0.0.1:2333` | 监听地址（仅限 http/sse 模式） |
### Docker / Podman
```bash
# 构建镜像
docker build -t mimi-tools .
# HTTP 模式（默认）
docker run -p 2333:2333 -v /projects:/projects mimi-tools:latest
# SSE 模式
docker run -p 2333:2333 -v /projects:/projects -e MIMI_TRANSPORT=sse mimi-tools:latest
```
> Podman 用户：将 `docker` 替换为 `podman` 在上述命令中。
<details>
<summary>🐉 中国用户 - 使用国内镜像加速构建</summary>
**选项 A：直接 `docker build` / `podman build`**
```bash
docker build \
--build-arg GOPROXY=https://goproxy.cn,direct \
--build-arg APT_MIRROR=mirrors.ustc.edu.cn \
--build-arg APT_SECURITY_MIRROR=mirrors.ustc.edu.cn/debian-security \
--build-arg NODE_MIRROR=https://npmmirror.com/mirrors/node \
--build-arg NPM_REGISTRY=https://registry.npmmirror.com \
-t mimi-tools .
```
**选项 B：通过 `deploy.sh`（推荐）**
在运行 `deploy.sh` 之前设置相同的变量：
```bash
GOPROXY=https://goproxy.cn,direct \
APT_MIRROR=mirrors.ustc.edu.cn \
APT_SECURITY_MIRROR=mirrors.ustc.edu.cn/debian-security \
NODE_MIRROR=https://npmmirror.com/mirrors/node \
NPM_REGISTRY=https://registry.npmmirror.com \
DNS_SERVER=223.5.5.5 DNS_SERVER2=223.6.6.6 \
./deploy.sh
```
</details>
## 部署
使用 `deploy.sh` 在 Podman 容器中部署：
```bash
# HTTP 模式（默认）
./deploy.sh
# SSE 模式
MIMI_TRANSPORT=sse ./deploy.sh
# 覆盖 git 用户身份
MIMI_GIT_USER_NAME="张三" MIMI_GIT_USER_EMAIL="zhangsan@example.com" ./deploy.sh
# 带有额外 git 配置（例如，签名密钥，默认分支）
MIMI_GIT_USER_NAME="张三" \
MIMI_GIT_USER_EMAIL="zhangsan@example.com" \
MIMI_GIT_CONFIG_EXTRA="[core]
autocrlf = input
[init]
defaultBranch = main" \
./deploy.sh
```
### 部署脚本环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `MIMI_TRANSPORT` | `http` | 容器传输模式（`http`、`sse`） |
| `DNS_SERVER` | `1.1.1.1` | 容器的主 DNS 服务器 |
| `DNS_SERVER2` | `1.0.0.1` | 容器的辅助 DNS 服务器 |
| `MIMI_GIT_CONFIG_DIR` | `~/.config/mimi-tools/git` | 生成的 `.gitconfig` 文件的主机路径 |
| `MIMI_GIT_USER_NAME` | `mimi-tools` | 容器 `.gitconfig` 中的 git 用户名 |
| `MIMI_GIT_USER_EMAIL` | `mimi-tools@localhost` | 容器 `.gitconfig` 中的 git 用户邮箱 |
| `MIMI_GIT_CONFIG_EXTRA` | *(空)* | 附加到 `.gitconfig` 的额外 git 配置行 |
| `MIMI_GO_CONFIG_DIR` | `~/.config/mimi-tools/go` | Go 环境配置的主机路径 |
| `GOPROXY` | *(空)* | Go 模块代理，作为 `podman build` 的 `--build-arg` 传递（例如 `https://goproxy.cn,direct`） |
| `APT_MIRROR` | *(空)* | APT 镜像，作为 `--build-arg` 传递（例如 `mirrors.ustc.edu.cn`） |
| `APT_SECURITY_MIRROR` | *(空)* | APT 安全镜像，作为 `--build-arg` 传递 |
| `NODE_MIRROR` | *(空)* | Node.js 下载镜像，作为 `--build-arg` 传递 |
| `NPM_REGISTRY` | *(空)* | NPM 仓库，作为 `--build-arg` 传递 |
| `USER_UID` | *(空)* | 容器用户 UID，作为 `--build-arg` 传递 |
| `USER_GID` | *(空)* | 容器用户 GID，作为 `--build-arg` 传递 |
## License
MIT
