KurrentDB MCP Server

What is KurrentDB MCP Server about?

Enables fast exploration of KurrentDB data by exposing stream operations and projection management through the Model Context Protocol. Users can read events, list streams, write new events, build and manage AI‑assisted projections, and monitor projection status.

How to use KurrentDB MCP Server?

1. Configure KurrentDB – start KurrentDB with --run-projections=all and --start-standard-projections.
2. Set the connection string – provide KURRENTDB_CONNECTION_STRING via environment variable.
3. Add an MCP client configuration – examples are given for Claude Desktop, VS Code, Cursor, and Windsurf. The client points to the server.py script (e.g., python path\to\server.py).
4. Invoke tools – from the MCP client call any of the eight exposed tools (read_stream, list_streams, write_events_to_stream, build_projection, etc.) with the required parameters.

Key Features of KurrentDB MCP Server

• Stream Operations: read, list, and write events to any KurrentDB stream.
• Projection Lifecycle: AI‑assisted building, creation, updating, testing, and status retrieval of projections.
• Environment‑Based Access Control: uses the KurrentDB connection string for authentication and authorization.
• Cross‑Client Compatibility: works with Claude Desktop, VS Code, Cursor, and Windsurf MCP configurations.
• Zero‑Installation Client: client configuration is JSON‑based, requiring only the server script to run.

Use Cases of KurrentDB MCP Server

• Rapid prototyping of new data views without writing full projection code.
• Debugging event streams by reading recent events and injecting test events.
• Monitoring projection health in production environments.
• Ad‑hoc analytics for business users who need quick answers from event data.
• Integration testing of projection logic via the test_projection tool.

FAQ from the KurrentDB MCP Server

• Q: Do I need to install any dependencies? A: The server runs on Python. Ensure Python 3 is installed and run uv run server.py or python server.py as shown in the client configs.
• Q: How is security handled? A: Access is controlled by the KurrentDB connection string supplied in the environment; no additional auth layer is provided.
• Q: Can I use this with other MCP clients? A: Yes, any MCP‑compatible client can connect as long as it follows the JSON configuration format.
• Q: What limits are there on reading streams? A: read_stream defaults to 10 events, configurable via the limit parameter; list_streams defaults to 100 streams.
• Q: How do I create a custom projection? A: Use build_projection with a natural‑language prompt, then pass the generated code to create_projection.

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.

MCP Client Setup (Claude or 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 Claude Desktop (https://modelcontextprotocol.io/quickstart/user) and VS Code (.vscode/mcp.json).

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