home / mcp / kurrentdb mcp server

KurrentDB MCP Server

Provides an MCP interface to explore KurrentDB streams, write events, and manage projections.

Installation

Add the following to your MCP client configuration file.

Configuration

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

You have a lightweight MCP server that exposes KurrentDB streams and projection tooling to your MCP clients. It lets you read streams, write events, and build, test, and run projections against your KurrentDB data, enabling rapid prototyping and data exploration.

How to use

You can connect different MCP clients to this server using stdio configurations that start the MCP runtime and launch the server script. Each client runs the MCP process in its own environment and communicates with the server over standard input/output. You’ll set the KURRENTDB_CONNECTION_STRING as an environment variable so the server can enforce access control against your KurrentDB instance.

How to install

Prerequisites and setup steps you’ll follow in order.

# Prerequisites
- Install Python (3.x) on your machine
- Install the required Python packages
  - Run: `pip install -r requirements.txt`
- Ensure the vu package is installed on the host
  - macOS: `brew install uv`

# Prepare MCP server files
- Place the MCP server folder containing `server.py` in a working directory

# Start the MCP server manually (example for local run)
- Run: `uv --directory <path to mcp-server folder> run server.py

Additional sections

Configuration and security notes: - Access control is enforced via the KurrentDB connection string you provide as an environment variable. Keep this string secure and do not share it publicly. - When you run multiple clients, consider isolating the MCP server process per client to avoid cross-client state sharing. - The server exposes tools to read streams, list streams, write events, and manage projections. Use a dedicated environment variable to point each client at the desired KurrentDB instance.

Tools and capabilities

The MCP server offers a set of tool endpoints to interact with KurrentDB data and projections: - read_stream - list_streams - write_events_to_stream - read_stream - build_projection - create_projection - update_projection - test_projection - get_projections_status These tools enable you to query streams, add new events, and manage projections including building, testing, and monitoring their status.

Sample events and usage patterns

To prototype a projection, you typically: - List streams to find your data sources - Create or update a projection that aggregates or transforms events - Test the projection with sample events and verify outputs - Retrieve status to confirm it’s running as expected

Available tools

read_stream

Reads events from a specific stream; you can specify stream name, direction, and limit to control the slice of events returned.

list_streams

Lists all available streams in the KurrentDB database with options to limit results and read order.

write_events_to_stream

Writes new events to a specific stream, including the event data, type, and metadata.

build_projection

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

create_projection

Creates a new projection in KurrentDB using provided code after your confirmation.

update_projection

Updates an existing projection with new code.

test_projection

Writes test events to a projection to verify its behavior and outputs.

get_projections_status

Retrieves status and statistics for a given projection.