Quick Start

Install, run, and make your first query in under 5 minutes.

Prerequisites

You need the Rust toolchain (1.75 or later). Install it with:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Build from source

git clone https://github.com/TeideDB/teidelum.git
cd teidelum
cargo build --release

The binary is at target/release/teidelum.

Run the server

./target/release/teidelum

Teidelum serves MCP over stdio. On first run, it generates demo data (team members, project tasks, incidents) so you can start querying immediately.

Set TEIDELUM_DATA to control where data is stored (defaults to ./data):

TEIDELUM_DATA=/path/to/data ./target/release/teidelum

HTTP Server Mode

Teidelum can also run as an HTTP server, exposing a REST API alongside MCP. Pass --port to enable it:

# MCP over stdio (default, backward compatible)
./target/release/teidelum

# HTTP server + MCP
./target/release/teidelum --port 8080

# Custom bind address and data directory
./target/release/teidelum --port 8080 --bind 0.0.0.0 --data /path/to/data

# With API key authentication
TEIDELUM_API_KEY=your-secret-key ./target/release/teidelum --port 8080

CLI Options

Options:
  --port <PORT>     Enable HTTP server on this port
  --bind <ADDR>     Bind address [default: 127.0.0.1]
  --data <DIR>      Data directory [default: data, env: TEIDELUM_DATA]

REST API Quick Examples

With the HTTP server running on port 8080, you can interact with Teidelum using plain HTTP requests:

# Create a table
curl -X POST http://localhost:8080/api/v1/tables \
  -H "Content-Type: application/json" \
  -d '{"name":"users","source":"app","columns":[{"name":"id","type":"int"},{"name":"name","type":"varchar"}],"rows":[[1,"Alice"],[2,"Bob"]]}'

# Query with SQL
curl -X POST http://localhost:8080/api/v1/sql \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT * FROM users"}'

# Full-text search
curl -X POST http://localhost:8080/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query":"authentication","limit":5}'

# List tables and schemas
curl http://localhost:8080/api/v1/describe

For the full list of endpoints, request/response schemas, and authentication details, see the API Reference.

Connect from Claude Desktop

Add Teidelum to your Claude Desktop MCP configuration at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "teidelum": {
      "command": "/path/to/teidelum"
    }
  }
}

Restart Claude Desktop to pick up the new server.

Your first queries

Once connected, try these prompts with your AI agent:

"Search for JWT token rotation" — triggers the search tool
"Show me all high-priority tasks" — triggers the sql tool
"Who is assigned to the most tasks?" — triggers sql with GROUP BY
"What's related to Alice Chen?" — triggers the graph tool

The agent will automatically choose the right MCP tool based on your request.