KurrentDB MCP Server

KurrentDB MCP Server

What is KurrentDB MCP Server about?

KurrentDB MCP Server provides a lightweight MCP endpoint that exposes stream data from a KurrentDB instance. It lets clients query events, list streams, and manage AI‑assisted projections without writing low‑level database code.

How to use KurrentDB MCP Server?

1. Prepare KurrentDB – start KurrentDB with --run-projections=all and --start-standard-projections enabled; the $streams stream is used for discovery.
2. Install dependencies – run pip install -r requirements.txt (or use uv as shown in the README).
3. Set the connection string – export KURRENTDB_CONNECTION_STRING with your credentials.
4. Start the server – uv run server.py (or python server.py).
5. Configure a client – add an MCP entry in VS Code, Claude Desktop, Cursor, or Windsurf using the JSON snippets from the README. The client will communicate with the server via STDIO.

Key Features

• Stream Operations: read_stream, write_events_to_stream, list_streams.
• Projection Lifecycle: build_projection (AI‑guided), create_projection, update_projection, test_projection, get_projections_status.
• Environment‑based access control using the KurrentDB connection string.
• Zero‑code prototyping – generate projection code from natural‑language prompts.
• Cross‑client compatibility – ready‑to‑use configurations for VS Code, Claude Desktop, Cursor, and Windsurf.

Use Cases

• Quickly prototype analytics views (e.g., daily revenue, order counts) without manual coding.
• Debug and test event‑driven projections by writing synthetic events and inspecting results.
• Build internal dashboards that query live streams for operational monitoring.
• Enable non‑technical team members to explore event data through natural‑language prompts.

FAQ

Q: Do I need Node.js to run this server?
A: No. The server is a Python application; uv or python is used to execute server.py.

Q: How are projections created?
A: Use the build_projection tool with a natural‑language description; the server returns generated code, which you then confirm and create via create_projection.

Q: Which environment variable supplies the DB connection?
A: KURRENTDB_CONNECTION_STRING.

Q: Can I list all streams in a large database?
A: Yes, list_streams supports a limit parameter (default 100) and a read_backwards flag for pagination.

Q: Is authentication handled by the server?
A: Access control relies on the credentials embedded in the connection string; the server does not implement additional auth layers.

KurrentDB MCP Server

This is a simple MCP server to help you explore data and prototype projections faster on top of KurrentDB.

Recommended Usage

• Claude Desktop
• Sequential Thinking MCP for complex tasks

Installation

KurrentDB Setup

You need to enable --run-projections=all and --start-standard-projections on KurrentDB The $streams stream is used to look for available streams.

Python Dependencies

Ensure the packages in requirements.txt are installed using pip

OS Dependencies

Ensure the vu package is installed on your machine where you will be running the MCP Server

For Mac: brew install uv

MCP Client Setup (VS Code)

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

This configuration file should work in VS Code (.vscode/mcp.json).

MCP Client Setup (Claude)

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

This configuration file should work in Claude Desktop (https://modelcontextprotocol.io/quickstart/user).

MCP Client Setup (Cursor or Windsurf)

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

This configuration file should work in Cursor (.cursor\mcp.json) and Windsurf (.codeium\windsurf\mcp_config.json).

Overview

This MCP server is designed to make stream data available to the MCP client. It provides a simple interface for querying and retrieving stream data. It can also create, test and debug projections.

Access control is done using the KurrentDB connection string provided at configuration time as an environment variable.

Components

Tools

The servers exposes 8 tool calls:

1. read_stream
2. list_streams
3. build_projection
4. create_projection
5. update_projection
6. test_projection
7. write_events_to_stream
8. get_projections_status

Configuration

• ConnectionString: This is a KurrentDB connection string which includes user credentials. Depending on the client being used, this can come from environment variable or a JSON Configuration file like in Claude Desktop's case.

Usage Documentation

Available Tools

1. Stream Operations

read_stream

Reads events from a specific stream in KurrentDB.

Parameters:

• stream (required): Stream name to read from
• backwards (optional, default: false): Read direction - true for newest first, false for oldest first
• limit (optional, default: 10): Number of events to return

Sample Prompts:

• "Read the last 5 events from the 'orders' stream"
• "Show me the first 20 events from the user-activity stream"
• "Get all events from the inventory stream, reading backwards"

Example Usage:

Tool: read_stream
Parameters:
- stream: "orders"
- backwards: true
- limit: 5

write_events_to_stream

Writes new events to a stream in KurrentDB.

Parameters:

• stream (required): Name of the stream to write to
• data (required): JSON object containing the event data
• event_type (required): Type/category of the event
• metadata (required): JSON object with additional event information

Sample Prompts:

• "Add a new order event to the orders stream with customer ID 123"
• "Record a user login event with timestamp and IP address"
• "Create a product update event in the inventory stream"

Example Usage:

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"}

list_streams

Lists all available streams in the KurrentDB database.

Parameters:

• limit (optional, default: 100): Number of streams to return
• read_backwards (optional, default: true): Read direction for the $streams stream

Sample Prompts:

• "Show me all streams in the database"
• "List the first 10 streams"
• "What streams are available in KurrentDB?"

Example Usage:

Tool: list_streams
Parameters:
- limit: 20
- read_backwards: true

2. Projection Operations

Projections in KurrentDB are computed views that process events from streams to create queryable data structures.

build_projection

Uses AI assistance to build a projection based on your requirements.

Parameters:

• user_prompt (required): Description of what the projection should do

Sample Prompts:

• "Create a projection that counts total orders by customer"
• "Build a projection showing daily revenue totals"
• "I need a projection that tracks inventory levels in real-time"

Example Usage:

Tool: build_projection
Parameters:
- user_prompt: "Create a projection that aggregates order totals by day and calculates running totals"

create_projection

Creates a projection in KurrentDB using provided code.

Parameters:

• projection_name (required): Name for the projection
• code (required): Generated projection code

Sample Prompts:

• "Create the customer analytics projection with the generated code"
• "Deploy this order summary projection to KurrentDB"

Note: Client normally always asks the user for confirmation before creating a projection.

update_projection

Updates an existing projection with new code.

Parameters:

• projection_name (required): Name of the projection to update
• code (required): Updated projection code

Sample Prompts:

• "Update the sales projection to include tax calculations"
• "Modify the user analytics projection to track more metrics"

get_projections_status

Retrieves status and statistics for a specific projection.

Parameters:

• projection_name (required): Name of the projection

Sample Prompts:

• "Check the status of the sales projection"
• "Show me statistics for the user-analytics projection"
• "Is the inventory projection running correctly?"

test_projection

Writes test events to a projection to verify its functionality. Verification is done by reading the streams emitted or the state of the projection.

Sample Prompts:

• "Test the order-analytics-projection with sample data"

Parameters:

• projection_name (required): Name of the projection to test

Sample Prompts:

• "How can I test the order analytics projection?"
• "Give me testing guidelines for the customer segmentation projection"

Sample Events

Modern LLMs can generate sample events for various use cases on their given enough information.

Order Event

{
  "data": {
    "orderId": "ORD-12345",
    "customerId": "CUST-789",
    "items": [
      {"productId": "PROD-001", "quantity": 2, "price": 29.99}
    ],
    "total": 59.98
  },
  "event_type": "OrderCreated",
  "metadata": {
    "timestamp": "2025-05-19T14:30:00Z",
    "source": "ecommerce-api",
    "correlationId": "corr-123"
  }
}

User Activity Event

{
  "data": {
    "userId": "USER-456",
    "action": "page_view",
    "page": "/products/electronics",
    "sessionId": "sess-789"
  },
  "event_type": "UserActivity",
  "metadata": {
    "timestamp": "2025-05-19T14:35:00Z",
    "userAgent": "Mozilla/5.0...",
    "ipAddress": "192.168.1.100"
  }
}