内容
# VoidMCP
统一调度所有MCP。
VoidMCP 是一个独立的MCP服务器，为您的AI代理提供**代码模式** - 编写和执行JavaScript的能力，以调度单个沙盒执行中的多个MCP工具。无需往返调用，无需浪费令牌，无需设置复杂性。
在运行时添加MCP。跨工具搜索。让您的代理编写脚本，将 GitHub + Notion + Slack + 任何具有MCP服务器的工具链接起来。
由 [VoidLLM](https://voidllm.ai) 背后的团队开发。
## 为什么
当您的AI代理可以访问10个MCP服务器和50多个工具时，会出现两个问题：
1. **令牌浪费** - 每次请求都会将每个工具模式发送到LLM
2. **往返调用开销** - 链接5个工具调用意味着5个LLM推理周期
VoidMCP解决了这两个问题。它公开了一个单一的`execute_code`工具。LLM编写一个JavaScript脚本，调用一个执行中的多个工具。一次推理，一个沙盒，多个工具调用。
```javascript
// 一个脚本，三个工具调用，零往返调用
const issues = await tools.github.search_issues({ q: "is:open label:bug" });
for (const issue of issues.items.slice(0, 5)) {
await tools.notion.create_page({ title: issue.title, content: issue.html_url });
}
await tools.slack.post_message({ channel: "#bugs", text: `Synced ${issues.items.length} issues` });
```
## 安装
```bash
go install github.com/voidmind-io/voidmcp/cmd/voidmcp@latest
```
或安装最新版本的二进制文件：
macOS / Linux：
```bash
curl -fsSL https://raw.githubusercontent.com/voidmind-io/voidmcp/main/install.sh | sh
```
Windows (PowerShell)：
```powershell
irm https://raw.githubusercontent.com/voidmind-io/voidmcp/main/install.ps1 | iex
```
手动下载也可在 [Releases](https://github.com/voidmind-io/voidmcp/releases) 上获取。
## 快速入门
### Claude 代码
```bash
claude mcp add --transport stdio voidmcp -- voidmcp serve --stdio
```
### Claude 桌面版
在您的 `claude_desktop_config.json` 中添加：
```json
{
"mcpServers": {
"voidmcp": {
"type": "stdio",
"command": "voidmcp",
"args": ["serve", "--stdio"]
}
}
}
```
### Cursor / Windsurf
相同的配置格式。如果 VoidMCP 二进制文件不在您的 PATH 中，请指向其完整路径。
## 添加MCP服务器
**公共服务器（无身份验证）** - AI代理可以直接添加：
> "在 https://weather.mcp.example.com 添加天气MCP"
**需要身份验证的服务器** - 使用CLI将令牌排除在LLM上下文之外：
```bash
voidmcp add github https://mcp.github.com --token ghp_your_token_here
voidmcp add notion https://mcp.notion.com --token ntn_your_token_here
voidmcp add myapi https://api.example.com/mcp --token secret --header X-Api-Key
```
**本地stdio服务器**（子进程）- 仅限CLI：
```bash
voidmcp add filesystem "npx -y @modelcontextprotocol/server-filesystem /home/user/docs"
voidmcp add sqlite "uvx mcp-server-sqlite --db /tmp/test.db"
```
您也可以通过CLI管理服务器：
```bash
voidmcp list # 显示已注册的服务器 + 工具
voidmcp remove filesystem # 注销服务器
```
## 工具
VoidMCP向LLM公开了5种工具：
| 工具 | 描述 |
|---|---|
| `add_mcp` | 注册一个HTTP MCP服务器（自动发现其工具） |
| `remove_mcp` | 注销服务器 |
| `list_mcps` | 列出所有已注册的服务器及其工具和状态 |
| `search` | 跨所有已注册的服务器按关键词查找工具 |
| `execute_code` | 在WASM沙盒中运行JavaScript，并访问所有已注册的工具 |
## 代码模式的工作原理
工作流程始终是：**先搜索，然后执行**。
1. LLM调用`search("your goal")`以发现具有完整TypeScript签名的相关工具
2. LLM调用`execute_code`，并使用JavaScript链接已发现的工具
3. VoidMCP将工具绑定注入到WASM沙盒QuickJS运行时
4. 脚本运行，支持`await`，调用多个服务器上的工具
5. VoidMCP返回结果、控制台日志和所有工具调用的摘要
沙盒无法访问主机文件系统、网络或环境。工具调用通过Go桥路由到正确的MCP传输。
### 模式推断
第一次调用工具时，VoidMCP捕获响应并推断其返回类型。在后续`search`调用中，TypeScript定义显示具体返回类型而不是`Promise<any>`：
```typescript
// 首次调用前：
function read_query(args: { query: string }): Promise<any>;
// 首次调用后：
function read_query(args: { query: string }): Promise<Array<{ id: number; name: string; email: string }>>;
```
推断的模式存储在SQLite中，并在7天后刷新（可通过`--schema-ttl`配置）。
## HTTP模式
适用于共享或远程部署：
```bash
voidmcp serve --port 8090
```
默认绑定到`127.0.0.1`。启动时生成一个Bearer令牌，并打印到标准错误流。使用`--host 0.0.0.0`暴露在网络上，使用`--no-auth`禁用令牌。
## 配置
所有设置都作为CLI标志提供：
```
voidmcp serve [flags]
--stdio 使用stdio传输（默认：HTTP）
--port int HTTP端口（默认：8090）
--host string 绑定地址（默认：127.0.0.1）
--no-auth 禁用Bearer令牌身份验证
--db string 数据库路径（默认：~/.voidmcp/voidmcp.db）
--pool-size int WASM运行时池大小（默认：4）
--memory int 每次执行的内存限制（MB）（默认：16）
--timeout duration 每次执行的超时时间（默认：30s）
--max-tool-calls int 每次执行的最多工具调用次数（默认：50）
```
已注册的服务器及其工具在重启后保存在SQLite中。
## 安全
- **WASM沙盒**：JavaScript在编译为WebAssembly的QuickJS中运行。无文件系统、网络或环境访问权限。每个执行后运行时都会被丢弃。
- **仅限本地主机**：HTTP服务器默认绑定到`127.0.0.1`
- **Bearer身份验证**：启动时为HTTP模式生成一个随机的256位令牌。
- **凭证从不触及LLM**：`add_mcp`工具仅接受公共URL（无身份验证）。需要令牌的服务器和本地stdio服务器只能通过CLI注册。这将API密钥排除在LLM上下文之外，并防止提示注入触发任意命令执行。
- **加密凭证**：身份验证令牌存储在SQLite中，使用AES-256-GCM加密。加密密钥位于`~/.voidmcp/key`，权限为0600。
- **受限子环境**：stdio MCP服务器仅接收PATH、HOME、TMPDIR、LANG来自父环境。
## 数据存储
```
~/.voidmcp/
voidmcp.db SQLite数据库（已注册服务器、缓存的工具模式）
key AES-256-GCM加密密钥（自动生成，chmod 0600）
```
## 许可证
MIT
## 相关
- [VoidLLM](https://voidllm.ai) - 面向团队的隐私优先LLM代理，内置代码模式
