内容
# spacetimedb-mcp-rs
基于Rust的[MCP](https://modelcontextprotocol.io/)服务器，暴露SpacetimeDB HTTP API作为MCP工具，允许LLMs查询数据库、调用约简器、执行SQL和管理身份。
## 功能
6类共15种工具：
| 类别 | 工具 |
|---|---|
| 身份验证 | `login` |
| 健康检查 | `ping` |
| 身份管理 | `create_identity`、`verify_identity`、`list_identity_databases` |
| 数据库 | `get_database`、`delete_database`、`get_database_names`、`add_database_name`、`set_database_names`、`resolve_database_identity`、`get_database_schema`、`get_database_logs` |
| SQL | `execute_sql` |
| 约简器 | `call_reducer` |
| 能量管理 | `get_energy_balance` |
## 身份验证
服务器支持三种身份验证方法，按顺序检查：
1. **静态令牌**（`SPACETIMEDB_TOKEN`环境变量）— 用于CI/无头使用
2. **保存的令牌**（`~/.spacetimedb/mcp_token.json`）— 如果过期则自动刷新
3. **浏览器登录** — 调用`login`工具通过SpacetimeAuth OIDC（GitHub、Google、Discord、Twitch、Kick或魔术链接）进行身份验证
如果没有可用的令牌，服务器将以未经身份验证的状态启动。使用`login`工具触发基于浏览器的OIDC登录，该登录为未来会话保存令牌。
## 先决条件
- 运行中的SpacetimeDB实例（或使用`https://testnet.spacetimedb.com`）
- （可选）用于身份验证操作的SpacetimeDB身份验证令牌
## 设置
### 1. 安装
从[Releases](../../releases)下载预构建的二进制文件，或从源代码构建：
```bash
cargo install --git https://github.com/Craigeous/spacetimedb-mcp-rs
```
### 2. 配置MCP客户端
#### Claude 代码
```bash
claude mcp add spacetimedb -- env SPACETIMEDB_URL=https://testnet.spacetimedb.com /path/to/spacetimedb-mcp-rs
```
或使用身份验证令牌：
```bash
claude mcp add spacetimedb -- env SPACETIMEDB_URL=https://testnet.spacetimedb.com SPACETIMEDB_TOKEN=your_token_here /path/to/spacetimedb-mcp-rs
```
#### Claude 桌面版
添加到您的Claude桌面配置（`~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"spacetimedb": {
"command": "/path/to/spacetimedb-mcp-rs",
"env": {
"SPACETIMEDB_URL": "https://testnet.spacetimedb.com",
"SPACETIMEDB_TOKEN": "your_token_here"
}
}
}
}
```
### 3. 验证
询问Claude： *"使用ping工具检查SpacetimeDB连接性"*
## 环境变量
| 变量 | 是否必需 | 描述 |
|---|---|---|
| `SPACETIMEDB_URL` | 是 | SpacetimeDB实例的基本URL |
| `SPACETIMEDB_TOKEN` | 否 | 静态JWT身份验证令牌 — 完全跳过OIDC |
| `SPACETIMEDB_CLIENT_ID` | 否 | OIDC客户端ID（默认值：内置） |
| `SPACETIMEDB_AUTH_URL` | 否 | OIDC授权URL（默认值：`https://auth.spacetimedb.com/oidc`） |
## 使用提示
- 使用`ping`验证连接性
- 如果未配置令牌，请使用`login`通过浏览器进行身份验证
- 使用`get_database_schema`在查询之前浏览数据库的表和约简器
- 使用`execute_sql`对SpacetimeDB表进行读取查询（SELECT）
- 使用`call_reducer`调用修改数据的存储过程
- 数据库参数接受人类可读的名称或十六进制标识字符串
- 使用`create_identity`获取新的身份和令牌用于身份验证操作
## 调试日志
```bash
RUST_LOG=debug SPACETIMEDB_URL=https://testnet.spacetimedb.com cargo run 2>debug.log
```
日志写入stderr，因此它们不会干扰MCP标准输入输出传输。
## 许可证
MIT
