雷恩设置
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 运维部署
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Docker
- 运行环境要求
- Docker
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
询问用户:主机上的哪个目录应安装为 MCP 工作区?这是读取和写入 MDL 文件和 YAML 项目目录的位置。 (例如:`~/wren-workspace`)如果用户没有偏好,建议创建一个专用目录,例如`~/wren-workspace`:
通过 http://localhost:9001 打开 Web UI。 Web UI 提供: 只读模式 — 切换以防止 AI 代理调用 `deploy`、`deploy_manifest`、`list_remote_tables` 或 `list_remote_constraints`。对于只读查询访问很有用。 MDL 状态 — 显示当前部署的 MDL(模型、列、数据源)。连接信息 — 选择数据源类型并填写凭据。单击“保存连接”进行测试并保留。
Claude Code 使用 Streamable-http 传输连接到容器化 MCP 服务器。通过Claude Code CLI(推荐):或者手动添加到`mcpServers`下的`~/.claude/settings.json`:添加后,重新启动Claude Code,以便将新的MCP服务器加载到会话中。确认: 注意:配置文件是`~/.claude/settings.json`,而不是`~/.claude.json`。在会话已运行时添加 MCP 服务器在会话重新启动之前不会生效。
要求 AI 代理运行健康检查: 预期响应:`SELECT 1` 返回成功结果。如果健康检查失败,请参阅下面的故障排除。
选项 A — 启动时自动加载(推荐):在启动容器之前将编译好的 `mdl.json` 放入 `<WORKSPACE_PATH>/target/mdl.json` 中。容器在启动时读取 `MDL_PATH` 并记录: 选项 B — 通过 Web UI 部署:打开 `http://localhost:9001`,在 MDL 编辑器中粘贴或编辑 MDL JSON,然后单击保存并部署。选项 C — 通过 MCP 工具部署(容器运行后):
# Set Up Wren MCP via Docker
## Version check
Silently fetch `https://raw.githubusercontent.com/Canner/wren-engine/main/skills/versions.json`.
Compare the `wren-mcp-setup` key with this skill's version (from the frontmatter above).
If the remote version is newer, notify the user before proceeding:
> A newer version of the **wren-mcp-setup** skill is available.
> Update with:
> ```
> npx skills add Canner/wren-engine --skill wren-mcp-setup --agent claude-code
> ```
Then continue with the workflow below regardless of update status.
---
Runs the Wren Engine ibis-server + MCP server together in a single Docker container and connects it to Claude Code (or another MCP client) over streamable-http.
---
## Step 1 — Ask for workspace path
Ask the user:
> What directory on your host machine should be mounted as the MCP workspace?
> This is where MDL files and YAML project directories will be read and written.
> (Example: `~/wren-workspace`)
If the user has no preference, suggest creating a dedicated directory such as `~/wren-workspace`:
```bash
mkdir -p ~/wren-workspace
```
Save the answer as `<WORKSPACE_PATH>` (use the absolute path, e.g. `/Users/me/wren-workspace`) for use in the next steps.
---
## Step 2 — Prepare workspace and start the container
### Check for a newer image
Before starting the container, verify whether a newer `wren-engine-ibis` image is available on the registry.
**If the image has never been pulled** (first-time setup), just pull it:
```bash
docker pull ghcr.io/canner/wren-engine-ibis:latest
```
**If the image already exists locally**, compare the local digest with the remote one to detect updates:
```bash
# Save current local digest (empty string if image not present)
LOCAL_DIGEST=$(docker inspect --format='{{index .RepoDigests 0}}' ghcr.io/canner/wren-engine-ibis:latest 2>/dev/null || echo "")
# Pull from registry (downloads only if remote digest differs)
docker pull ghcr.io/canner/wren-engine-ibis:latest
# Compare digests
NEW_DIGEST=$(docker inspect --format='{{index .RepoDigests 0}}' ghcr.io/canner/wren-engine-ibis:latest 2>/dev/null || echo "")
if [ "$LOCAL_DIGEST" != "$NEW_DIGEST" ]; then
echo "✓ New image pulled — container will use the updated version."
else
echo "✓ Already up to date. No update was needed."
fi
```
> **Note:** If a `wren-mcp` container is already running and a new image was pulled, stop and remove the old container before proceeding:
> ```bash
> docker rm -f wren-mcp
> ```
The workspace directory is mounted at `/workspace` inside the container. Place your compiled MDL at `<WORKSPACE_PATH>/target/mdl.json` so the container can load it at startup via `MDL_PATH`.
**Recommended workspace layout:**
```
<WORKSPACE_PATH>/
└── target/
└── mdl.json # Compiled MDL (from wren-project build)
```
> **Note:** Connection info is managed via the MCP server Web UI (see Step 3) and persisted to `~/.wren/connection_info.json`. You can also pre-configure this file before starting the container.
Run the following command, substituting `<WORKSPACE_PATH>` with the path from Step 1:
```bash
docker run -d \
--name wren-mcp \
-p 8000:8000 \
-p 9000:9000 \
-p 9001:9001 \
-e ENABLE_MCP_SERVER=true \
-e MCP_TRANSPORT=streamable-http \
-e MCP_HOST=0.0.0.0 \
-e MCP_PORT=9000 \
-e WREN_URL=localhost:8000 \
-e MDL_PATH=/workspace/target/mdl.json \
-v <WORKSPACE_PATH>:/workspace \
ghcr.io/canner/wren-engine-ibis:latest
```
Example with a concrete path:
```bash
docker run -d \
--name wren-mcp \
-p 8000:8000 \
-p 9000:9000 \
-p 9001:9001 \
-e ENABLE_MCP_SERVER=true \
-e MCP_TRANSPORT=streamable-http \
-e MCP_HOST=0.0.0.0 \
-e MCP_PORT=9000 \
-e WREN_URL=localhost:8000 \
-e MDL_PATH=/workspace/target/mdl.json \
-v /Users/me/wren-workspace:/workspace \
ghcr.io/canner/wren-engine-ibis:latest
```
> If `MDL_PATH` is not set or the file doesn't exist yet, the container starts without a loaded MDL. You can deploy later using the `deploy` MCP tool or the Web UI.
This starts the container using the image `ghcr.io/canner/wren-engine-ibis:latest` with:
| Service | Port | Purpose |
|---------|------|---------|
| ibis-server | 8000 | REST API for query execution and metadata |
| mcp-server (streamable-http) | 9000 | MCP endpoint for AI clients |
| Web UI | 9001 | Configuration UI (connection info, MDL editor, read-only mode) |
The workspace directory is mounted at `/workspace` inside the container.
Verify the container is running:
```bash
docker ps --filter name=wren-mcp
docker logs -f wren-mcp
```
---
## Step 3 — Configure connection info via Web UI
Open the Web UI at **http://localhost:9001**.
The Web UI provides:
- **Read-only Mode** — toggle to prevent the AI agent from calling `deploy`, `deploy_manifest`, `list_remote_tables`, or `list_remote_constraints`. Useful for read-only query access.
- **MDL Status** — shows the currently deployed MDL (models, columns, data source).
- **Connection Info** — select the data source type and fill in credentials. Click **Save Connection** to test and persist.
- **MDL Editor** — view and edit the live MDL JSON inline. Click **Save & Deploy** to update.
### Docker host hint
**Critical:** The container cannot reach the host's `localhost` directly. If your database runs on the host machine, use `host.docker.internal` instead of `localhost` or `127.0.0.1` as the hostname.
The Web UI shows a hint for this when it detects you may be connecting to a local database:
| Original | Inside Docker |
|----------|--------------|
| `localhost` | `host.docker.internal` |
| `127.0.0.1` | `host.docker.internal` |
| Cloud/remote host (e.g. `mydb.us-east-1.rds.amazonaws.com`) | No change needed |
Fill in the connection credentials in the Web UI form, apply the Docker host hint if needed, and click **Save Connection**.
---
## Step 4 — Configure Claude Code MCP
Claude Code uses **streamable-http** transport to connect to the containerized MCP server.
**Via Claude Code CLI (recommended):**
```bash
claude mcp add --transport http wren http://localhost:9000/mcp
```
Or add manually to `~/.claude/settings.json` under `mcpServers`:
```json
{
"mcpServers": {
"wren": {
"type": "http",
"url": "http://localhost:9000/mcp"
}
}
}
```
After adding, **restart Claude Code** for the new MCP server to be loaded into the session. Confirm with:
```bash
claude mcp list
```
> **Note:** The config file is `~/.claude/settings.json`, not `~/.claude.json`. Adding the MCP server while a session is already running has no effect until the session is restarted.
---
## Step 5 — Configure other MCP clients
### Cline / Cursor / VS Code MCP Extension
These clients also support HTTP transport. Add to their MCP settings:
```json
{
"mcpServers": {
"wren": {
"type": "streamable-http",
"url": "http://localhost:9000/mcp"
}
}
}
```
### Claude Desktop (stdio fallback)
Claude Desktop does not support HTTP transport natively. Use a local stdio proxy or run the MCP server locally instead.
---
## Step 6 — Verify the connection
Ask the AI agent to run a health check:
```
Use the health_check() tool to verify Wren Engine is reachable.
```
Expected response: `SELECT 1` returns a successful result.
If health check fails, see **Troubleshooting** below.
---
## Troubleshooting — MCP server not healthy
### 1. Check container status and logs
```bash
docker ps --filter name=wren-mcp
docker logs wren-mcp
```
Look for startup errors or crash loops. If the container exited, `logs` will show the last output before it stopped.
### 2. Port already in use
The container exposes ports **8000** (ibis-server), **9000** (MCP), and **9001** (Web UI). If any port is already bound by another process on the host, the `docker run` command will fail with a bind error.
**Check what is using the port:**
```bash
# macOS / Linux
lsof -i :9000
lsof -i :8000
lsof -i :9001
```
If another process is occupying the port you have two options:
**Option A — stop the conflicting process:**
```bash
# macOS: kill by port
kill $(lsof -ti :9000)
```
**Option B — remap to different host ports:**
Stop and remove the existing container first, then re-run with different host-side ports:
```bash
docker rm -f wren-mcp
docker run -d \
--name wren-mcp \
-p 18000:8000 \
-p 19000:9000 \
-p 19001:9001 \
-e ENABLE_MCP_SERVER=true \
-e MCP_TRANSPORT=streamable-http \
-e MCP_HOST=0.0.0.0 \
-e MCP_PORT=9000 \
-e WREN_URL=localhost:8000 \
-e WEB_UI_PORT=9001 \
-e MDL_PATH=/workspace/target/mdl.json \
-v <WORKSPACE_PATH>:/workspace \
ghcr.io/canner/wren-engine-ibis:latest
```
Then update the MCP client URL and Web UI address to match:
```bash
claude mcp add --transport http wren http://localhost:19000/mcp
# Web UI: http://localhost:19001
```
### 3. Container started but MCP endpoint returns an error
- Confirm the container was started with `-e ENABLE_MCP_SERVER=true`, `-e MCP_TRANSPORT=streamable-http`, and `-e MCP_HOST=0.0.0.0`
- Try curling the endpoint directly:
```bash
curl -v http://localhost:9000/mcp
```
A `405 Method Not Allowed` response means the endpoint is reachable but expects a POST — that is normal and indicates the MCP server is up.
### 4. MCP tools fail with "Session not found" after container restart
Container restarts invalidate all active MCP sessions. The AI client still holds the old session ID, so every MCP call returns `"Session not found"`. **Start a new Claude Code session** (or restart your MCP client) to reconnect.
### 5. Database connection refused inside the container
If `health_check()` passes but queries fail with a connection error, the database host is likely still set to `localhost`. Open the Web UI at `http://localhost:9001`, edit the connection info, and change the host to `host.docker.internal`.
---
## Step 7 — Load an MDL and start querying
**Option A — Auto-load at startup (recommended):**
Place your compiled `mdl.json` in `<WORKSPACE_PATH>/target/mdl.json` before starting the container. The container reads `MDL_PATH` at startup and logs:
```
Loaded MDL /workspace/target/mdl.json (9 models, 47 columns)
```
**Option B — Deploy via Web UI:**
Open `http://localhost:9001`, paste or edit your MDL JSON in the MDL Editor, and click **Save & Deploy**.
**Option C — Deploy via MCP tool (after container is running):**
In the AI client (after MCP is connected):
```
deploy(mdl_file_path="/workspace/target/mdl.json")
```
Or deploy from an in-memory dict:
```
deploy_manifest(mdl=<manifest dict>)
```
**To generate an MDL from scratch**, use the `wren-generate-mdl` skill. It will introspect your database schema via ibis-server and build the manifest for you.
---
## You're ready!
Start a **new Claude Code session** (or restart your MCP client). The Wren tools (`health_check`, `query`, `deploy`, `setup_connection`, etc.) are now available.
Try it:
```
Use health_check() to verify the connection.
```
Once confirmed, you can start querying your data through Wren Engine — use `/wren-generate-mdl` to scaffold an MDL from your database, or `/wren-sql` for help writing queries.
---
> Source: [Canner/wren-engine](https://github.com/Canner/wren-engine) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
按说明文件中的顺序排列。
版本检查
第 1 步 - 询问工作空间路径
检查是否有较新的图像
第 3 步 — 通过 Web UI 配置连接信息
Docker 主机提示
文件/命令 -> https://raw.githubusercontent.com/Canner/wren-engine/main/skills/versions.json · wren-mcp-setup · ~/wren-workspace · <WORKSPACE_PATH> · /Users/me/wren-workspace · wren-engine-ibis · wren-mcp · /workspace
内容校验值 -> 366a7eb750d9
当前原文的自动摘译,尚未人工审校。
版本检查
默默地获取
https://raw.githubusercontent.com/Canner/wren-engine/main/skills/versions.json。将wren-mcp-setup键与该技能的版本进行比较(来自上面的前文)。如果远程版本较新,请在继续之前通知用户:有较新版本的 wren-mcp-setup 技能可用。更新为:第 1 步 - 询问工作空间路径
询问用户:您的主机上的哪个目录应安装为 MCP 工作区?这是读取和写入 MDL 文件和 YAML 项目目录的位置。 (例如:
~/wren-workspace)如果用户没有偏好,建议创建一个专用目录,例如~/wren-workspace:检查是否有较新的图像
在启动容器之前,请验证注册表中是否有更新的
wren-engine-ibis映像可用。如果图像从未被拉取(第一次设置),只需拉取它:如果图像本地已存在,则将本地摘要与远程摘要进行比较以检测更新:注意:如果wren-mcp容器已在运行并且拉取了新图像,请在继续之前停止并删除旧容器:Docker 主机提示
严重:容器无法直接到达主机的
localhost。如果您的数据库在主机上运行,请使用host.docker.internal而不是localhost或127.0.0.1作为主机名。当 Web UI 检测到您可能正在连接到本地数据库时,会显示一条提示: Original · Inside Dockerlocalhost·host.docker.internal127.0.0.1·host.docker.internal