Content
# spacetimedb-mcp-rs
A Rust-based [MCP](https://modelcontextprotocol.io/) server that exposes the SpacetimeDB HTTP API as MCP tools, allowing LLMs to query databases, call reducers, execute SQL, and manage identities.
## Features
15 tools across 6 categories:
| Category | Tools |
|---|---|
| Auth | `login` |
| Health | `ping` |
| Identity | `create_identity`, `verify_identity`, `list_identity_databases` |
| Database | `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` |
| Reducer | `call_reducer` |
| Energy | `get_energy_balance` |
## Authentication
The server supports three authentication methods, checked in order:
1. **Static token** (`SPACETIMEDB_TOKEN` env var) — for CI/headless use
2. **Saved token** (`~/.spacetimedb/mcp_token.json`) — auto-refreshed if expired
3. **Browser login** — call the `login` tool to authenticate via SpacetimeAuth OIDC (GitHub, Google, Discord, Twitch, Kick, or magic link)
If no token is available, the server starts unauthenticated. Use the `login` tool to trigger browser-based OIDC login, which saves the token for future sessions.
## Prerequisites
- A running SpacetimeDB instance (or use `https://testnet.spacetimedb.com`)
- (Optional) A SpacetimeDB auth token for authenticated operations
## Setup
### 1. Install
Download a prebuilt binary from [Releases](../../releases), or build from source:
```bash
cargo install --git https://github.com/Craigeous/spacetimedb-mcp-rs
```
### 2. Configure your MCP client
#### Claude Code
```bash
claude mcp add spacetimedb -- env SPACETIMEDB_URL=https://testnet.spacetimedb.com /path/to/spacetimedb-mcp-rs
```
Or with an auth token:
```bash
claude mcp add spacetimedb -- env SPACETIMEDB_URL=https://testnet.spacetimedb.com SPACETIMEDB_TOKEN=your_token_here /path/to/spacetimedb-mcp-rs
```
#### Claude Desktop
Add to your Claude Desktop config (`~/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. Verify
Ask Claude: *"Use the ping tool to check SpacetimeDB connectivity"*
## Environment Variables
| Variable | Required | Description |
|---|---|---|
| `SPACETIMEDB_URL` | Yes | Base URL of the SpacetimeDB instance |
| `SPACETIMEDB_TOKEN` | No | Static JWT auth token — skips OIDC entirely |
| `SPACETIMEDB_CLIENT_ID` | No | OIDC client ID (default: built-in) |
| `SPACETIMEDB_AUTH_URL` | No | OIDC authority URL (default: `https://auth.spacetimedb.com/oidc`) |
## Usage Tips
- Start with `ping` to verify connectivity
- Use `login` to authenticate via browser if no token is configured
- Use `get_database_schema` to explore a database's tables and reducers before querying
- Use `execute_sql` for read queries (SELECT) against SpacetimeDB tables
- Use `call_reducer` to invoke stored procedures that modify data
- Database parameters accept either a human-readable name or a hex identity string
- Use `create_identity` to get a new identity and token for authenticated operations
## Debug Logging
```bash
RUST_LOG=debug SPACETIMEDB_URL=https://testnet.spacetimedb.com cargo run 2>debug.log
```
Logs are written to stderr so they don't interfere with the MCP stdio transport.
## License
MIT
