Content
# mimi-tools
[](https://go.dev)
[](LICENSE)
[](https://github.com/mimichat-ai/mimi-tools/actions/workflows/go.yml)
MCP tool server built with Go + MCP SDK. Provides LLM-callable tools: exec (cross-platform shell command), read, write, edit (with fuzzy matching), search_name, search_content, tree. Supports Streamable HTTP/SSE/stdio transport modes.
## Features
- **exec**: Execute commands on the system using shell
- **read**: Read file content with optional line range
- **write**: Write content to a file, creating parent directories if needed
- **edit**: Edit a file by replacing a matched string. Supports exact match and fuzzy matching (ignoring whitespace differences)
- **tree**: Show directory tree structure
- **search_name**: Search for files by name pattern in a directory tree (supports glob, regex, and substring matching; defaults to glob)
- **search_content**: Search for text content in files
> ⚠️ **Security Warning**
> The `exec` tool allows arbitrary shell command execution. This is by design (it enables LLM agents to build, test, and debug code), but it also means:
> - **Never expose the HTTP/SSE endpoint to the public internet** without additional authentication/authorization
> - **Run inside a container** (see Docker section) to sandbox the execution environment
> - **Use with trusted LLM agents only** — a malicious prompt could lead to command injection
> - For production deployments, restrict file access via OS-level permissions
## Quick Start
```bash
# Build
go build -o mimi-tools ./cmd/mimi-tools
# Run in stdio mode (for local MCP clients like Claude Desktop)
MIMI_TRANSPORT=stdio ./mimi-tools
# Or run as HTTP server (default, listens on localhost only)
./mimi-tools
# Server listening on http://127.0.0.1:2333
```
> ⚠️ **Bare-metal Security Notice**
> The default bind address is `127.0.0.1` (localhost only). The `exec` tool allows
> arbitrary shell command execution — do not change the bind address to `0.0.0.0`
> on shared or public servers without additional authentication/authorization.
> For remote deployments, use the Docker container (see below) which provides
> network isolation via container boundaries.
### Integrate with MCP Clients
Configure your MCP client (e.g., Claude Desktop) to connect to mimi-tools:
**stdio mode** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"mimi-tools": {
"command": "/path/to/mimi-tools",
"args": [],
"env": { "MIMI_TRANSPORT": "stdio" }
}
}
}
```
**HTTP mode** (for remote clients):
```json
{
"mcpServers": {
"mimi-tools": {
"url": "http://localhost:2333/"
}
}
}
```
## Transport Modes
mimi-tools supports three transport modes, controlled by the `MIMI_TRANSPORT` environment variable:
| Mode | Environment Variable | Description |
|------|---------------------|-------------|
| HTTP | `MIMI_TRANSPORT=http` | Streamable HTTP (default) |
| SSE | `MIMI_TRANSPORT=sse` | Server-Sent Events |
| Stdio | `MIMI_TRANSPORT=stdio` | Standard Input/Output |
### HTTP Mode (Default)
```bash
MIMI_TRANSPORT=http mimi-tools
# or
mimi-tools # defaults to http
```
Listens on `MIMI_ADDR` (default: `127.0.0.1:2333`). Clients send POST requests to the server.
### SSE Mode
```bash
MIMI_TRANSPORT=sse mimi-tools
```
Listens on `MIMI_ADDR` (default: `127.0.0.1:2333`). Clients connect via GET to `/sse` for Server-Sent Events.
### Stdio Mode
```bash
MIMI_TRANSPORT=stdio mimi-tools
```
Reads from stdin and writes to stdout. Suitable for local MCP client integration.
## Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `MIMI_TRANSPORT` | `http` | Transport mode: `http`, `sse`, or `stdio` |
| `MIMI_ADDR` | `127.0.0.1:2333` | Listen address (only for http/sse modes) |
### Docker / Podman
```bash
# Build image
docker build -t mimi-tools .
# HTTP mode (default)
docker run -p 2333:2333 -v /projects:/projects mimi-tools:latest
# SSE mode
docker run -p 2333:2333 -v /projects:/projects -e MIMI_TRANSPORT=sse mimi-tools:latest
```
> Podman users: replace `docker` with `podman` in the commands above.
<details>
<summary>🐉 For users in China — use domestic mirrors for faster builds</summary>
**Option A: Direct `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 .
```
**Option B: Via `deploy.sh` (recommended)**
Set the same variables as environment variables before running `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>
## Deployment
Use `deploy.sh` to deploy in a Podman container:
```bash
# HTTP mode (default)
./deploy.sh
# SSE mode
MIMI_TRANSPORT=sse ./deploy.sh
# Override git user identity
MIMI_GIT_USER_NAME="Zhang San" MIMI_GIT_USER_EMAIL="zhangsan@example.com" ./deploy.sh
# With extra git config (e.g., signing key, default branch)
MIMI_GIT_USER_NAME="Zhang San" \
MIMI_GIT_USER_EMAIL="zhangsan@example.com" \
MIMI_GIT_CONFIG_EXTRA="[core]
autocrlf = input
[init]
defaultBranch = main" \
./deploy.sh
```
### Deploy Script Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `MIMI_TRANSPORT` | `http` | Container transport mode (`http`, `sse`) |
| `DNS_SERVER` | `1.1.1.1` | Primary DNS server for the container |
| `DNS_SERVER2` | `1.0.0.1` | Secondary DNS server for the container |
| `MIMI_GIT_CONFIG_DIR` | `~/.config/mimi-tools/git` | Host path for generated `.gitconfig` file |
| `MIMI_GIT_USER_NAME` | `mimi-tools` | Git user name in container's `.gitconfig` |
| `MIMI_GIT_USER_EMAIL` | `mimi-tools@localhost` | Git user email in container's `.gitconfig` |
| `MIMI_GIT_CONFIG_EXTRA` | *(empty)* | Additional git config lines appended to `.gitconfig` |
| `MIMI_GO_CONFIG_DIR` | `~/.config/mimi-tools/go` | Host path for Go environment config |
| `GOPROXY` | *(empty)* | Go module proxy, passed as `--build-arg` to `podman build` (e.g. `https://goproxy.cn,direct`) |
| `APT_MIRROR` | *(empty)* | APT mirror, passed as `--build-arg` (e.g. `mirrors.ustc.edu.cn`) |
| `APT_SECURITY_MIRROR` | *(empty)* | APT security mirror, passed as `--build-arg` |
| `NODE_MIRROR` | *(empty)* | Node.js download mirror, passed as `--build-arg` |
| `NPM_REGISTRY` | *(empty)* | NPM registry, passed as `--build-arg` |
| `USER_UID` | *(empty)* | Container user UID, passed as `--build-arg` |
| `USER_GID` | *(empty)* | Container user GID, passed as `--build-arg` |
## License
MIT
