Kurrent logo

Find articles, guides, tutorials, and more.

Kurrent logo
Login Sign Up

Introducing the KurrentDB MCP Server

Lokhesh Ujhoodha avatar
Lokhesh Ujhoodha
•
AI Python MCP

Introducing KurrentDB MCP Server

Model Context Protocol (MCP) is a standard introduced by Anthropic for connecting AI assistants to the systems where data lives. Its aim is to help frontier models produce better, more relevant responses. The KurrentDB MCP Server allows you to use your favourite MCP Client, like Claude Desktop, or your favourite IDE to interface with your data inside KurrentDB either with specific prompts or just natural language.

KurrentDB MCP Server

Getting Started

TIP

Disclaimer: Please try the MCP Server in a development environment first.

Installation

Start with cloning the GitHub repository. We recommend the following in order to have the best experience:

MCP Client Configuration

Play

If you are using Claude Desktop or VS Code with GitHub Copilot you will have to configure it. If you need help finding your configuration, check the MCP Quickstart Guide or create a .vscode/mcp.json file on 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"
      }
    }
  }
}

We have additional installation instructions available in the GitHub repository.

Stream Management Examples

Play

Below are a few example prompts and their output from a dummy order related database

Listing Streams

The AI assistant uses the MCP server to call the list_streams function, which returns a list of all streams in your KurrentDB instance.

User query:

List all the streams in my KurrentDB database.

AI agent call:

list_streams(limit=100, read_backwards=True)

Response:

{
  "streams": [
    "customer-123",
    "orders",
    "inventory",
    "shipping-notifications",
    "$projections-CustomerOrders"
  ]
}

Reading from a Stream

The AI assistant calls the read_stream function to retrieve events:

User query:

Show me the last 5 events from the 'orders' stream.

AI agent call:

read_stream(stream="orders", backwards=True, limit=5)

Response:

{
  "events": [
    {
      "eventId": "c37fd21c-8e7a-4e09-a282-47e9e3e0c350",
      "eventType": "OrderShipped",
      "data": {
        "orderId": "ORD-29384",
        "shippingProvider": "FedEx",
        "trackingNumber": "FX8273648592"
      },
      "metadata": {
        "userId": "user-567",
        "timestamp": "2025-05-16T14:32:45Z"
      }
    },
    /* 4 more events... */
  ]
}

Write to a Stream

The AI assistant helps format the data and uses write_events_to_stream:

User query:

Create a new OrderPlaced event in the orders stream with orderId ORD-29385,
customerName 'Jane Smith', total amount $125.99, and 3 items.

AI agent calls:

write_events_to_stream(
    stream="orders",
    event_type="OrderPlaced",
    data={
        "orderId": "ORD-29385",
        "customerName": "Jane Smith", 
        "totalAmount": 125.99,
        "itemCount": 3
    },
    metadata={
        "userId": "user-567",
        "timestamp": "2025-05-20T09:45:22Z"
    }
)

Response:

{
  "success": true,
  "logPosition": 1253,
  "nextExpectedVersion": 42
}

Projection Management Examples

The MCP Server allows you to not only create projections but to also test and fix them. In this article we will explore how easy it is to create a projection with the MCP Server.

The AI assistant uses build_projection to generate projection code:

User query:

Help me create a projection that groups orders
by customer and calculates their total spending.

AI agent call:

build_projection(user_prompt="Create a projection that groups orders by customer and calculates their total spending")

Response:

{
  "code": """
  fromStream('orders')
  .when({
    $init: function() {
      return {
        customerSpending: {}
      };
    },
    OrderPlaced: function(state, event) {
      var customerId = event.data.customerName;
      var amount = event.data.totalAmount;
      
      if (!state.customerSpending[customerId]) {
        state.customerSpending[customerId] = 0;
      }
      
      state.customerSpending[customerId] += amount;
      
      return state;
    }
  })
  .outputState();
  """
}

Testing the Projection

The MCP Server knows that it needs to test the projection after creating it. It does this by asking the Client to build sample events and checking the output streams and the state stream. This should be done automatically but you can also call it explicitly. For example, it generates the following events to test the projection:

test_projection(projection_name="CustomerSpending")

Result:

{
  "success": true,
  "testResults": [
    {
      "eventType": "OrderPlaced",
      "testInput": {
        "customerName": "Jane Smith",
        "totalAmount": 125.99
      },
      "stateAfter": {
        "customerSpending": {
          "Jane Smith": 125.99
        }
      }
    },
    {
      "eventType": "OrderPlaced",
      "testInput": {
        "customerName": "Jane Smith",
        "totalAmount": 75.50
      },
      "stateAfter": {
        "customerSpending": {
          "Jane Smith": 201.49
        }
      }
    }
  ]
}

And then it reads the following streams to verify the logic:

get_projections_status(projection_name="CustomerSpending")

Response:

{
  "name": "CustomerSpending",
  "status": "Running",
  "progress": "100%",
  "position": "1253/1253",
  "lastCheckpoint": "2025-05-20T09:48:12Z",
  "mode": "Continuous",
  "stateSize": 2.3, // KB
  "state": {
    "customerSpending": {
      "Jane Smith": 201.49,
      "John Doe": 354.87,
      "Alice Johnson": 89.99
    }
  }
}

Next Steps

We believe in the power of open source to drive innovation and collaboration. By sharing our work with the community, we hope to create something better—together. Whether you’re an experienced developer or just starting out, your contributions are welcome and valued. If you’re interested in getting involved, take a look at the good first issues to find a place to start. We also encourage feedback, ideas, and questions—feel free to join the conversation in the Discussions tab on GitHub. Let’s build something great together.

Back to all posts