Overview

KurrentDB MCP Server is a lightweight Model Context Protocol (MCP) server that makes it fast and easy to explore event streams and prototype projections on top of KurrentDB. It exposes a small set of tools for listing and reading streams, writing events, and creating, testing, and managing projections — allowing developers to iterate on computed views (projections) in minutes rather than hours.

This server is intended for local development, experimentation, and fast prototyping. It uses a KurrentDB connection string for access control and integrates with MCP-capable clients (VS Code, Claude Desktop, Cursor, Windsurf, etc.) over stdio. Typical workflows include reading recent events, building projection code with AI assistance, deploying projections to KurrentDB, and running projection tests against sample event sets.

Features

Read and list streams from KurrentDB (including $streams discovery)
Append events to any stream
Generate projection code with AI-assisted prompts
Create, update, test, and debug projections in KurrentDB
Return projection status and health information
Simple stdio-based MCP integration for common editors/clients
Configured via environment variable (KURRENTDB_CONNECTION_STRING)

Installation / Configuration

Prerequisites

A running KurrentDB instance with projections enabled:
- Start KurrentDB with: –run-projections=all –start-standard-projections
- The server looks at the $streams stream to discover available streams
Python environment (server is a Python MCP server)
A small OS dependency: a CLI program named uv (used to run the MCP server in some client configs)

Python dependencies

# from the mcp-server repository
pip install -r requirements.txt

OS dependency (example for macOS)

# If you use Homebrew and the package is available
brew install uv

Environment

export KURRENTDB_CONNECTION_STRING="Host=...;User=...;Password=..."
# or set this in your editor/client MCP server configuration

Client configuration examples

VS Code (.vscode/mcp.json)

{
  "servers": {
    "KurrentDB": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-server",
        "run",
        "server.py"
      ],
      "env": {
        "KURRENTDB_CONNECTION_STRING": "insert kurrentdb connection here"
      }
    }
  }
}

Claude Desktop (mcp configuration)

{
  "mcpServers": {
    "KurrentDB": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-server",
        "run",
        "server.py"
      ],
      "env": {
        "KURRENTDB_CONNECTION_STRING": "insert kurrentdb connection here"
      }
    }
  }
}

Cursor or Windsurf

{
  "mcpServers": {
    "kurrentdb": {
      "command": "python",
      "args": ["/path/to/mcp-server/server.py"],
      "env": {
        "KURRENTDB_CONNECTION_STRING": "insert kurrentdb connection here"
      }
    }
  }
}

Available Tools

The server exposes these MCP tool calls. Use them from your MCP-capable client.

Tool	Purpose	Key parameters
read_stream	Read events from a stream	stream, backwards, limit
list_streams	List available streams	limit, read_backwards
write_events_to_stream	Append event(s) to a stream	stream, data, event_type, metadata
build_projection	Generate projection code from a prompt	user_prompt
create_projection	Deploy new projection to KurrentDB	projection_name, code
update_projection	Update existing projection code	projection_name, code
test_projection	Run a projection against sample events	projection_name, events
get_projections_status	Retrieve status for projections	projection_name (optional)

Read stream example

Tool: read_stream
Parameters:
{
  "stream": "orders",
  "backwards": true,
  "limit": 5
}

Write event example

Tool: write_events_to_stream
Parameters:
{
  "stream": "orders",
  "data": {"orderId":"ORD-001","customerId":123,"amount":99.99},
  "event_type": "OrderCreated",
  "metadata": {"timestamp":"2025-05-19T10:00:00Z","source":"web"}
}

Projection workflow

build_projection — provide a natural-language description to generate projection code.
review and confirm the code.
create_projection or update_projection — deploy to KurrentDB.
test_projection — run the projection against sample events to validate behavior.
get_projections_status — monitor status and health.

Note: Clients typically prompt users before creating/updating projections to avoid accidental deployment.

Use Cases

Rapid prototyping: Turn a prompt like “aggregate order totals by day with running totals” into projection code in minutes, then deploy and test locally.
Data exploration: Use list_streams and read_stream to discover and inspect recent events for debugging or analytics.
Integration testing: Write synthetic events to streams and test projections to validate business logic before deploying to production.
Iterative development: Update a projection, run tests against a curated event set, and monitor status without leaving your editor.

Tips and Best Practices

Always set KURRENTDB_CONNECTION_STRING securely (do not check credentials into source control).
Use small sample event sets with test_projection to iterate quickly before running on production-scale streams.
The $streams stream is useful for programmatically discovering stream names and metadata.
Review generated projection code before deploying — AI assists in generation but manual review avoids logic errors.

For more details, consult the repository README and the projection API docs in your KurrentDB installation.

KurrentDB MCP Server for Data Projections