Server Ladybug

MCP Badge

An MCP server implementation that interacts with LadybugDB graph databases, providing Cypher query capabilities to AI Assistants and IDEs.

About LadybugDB

LadybugDB is an embedded graph database built for query speed and scalability. It is optimized for handling complex join-heavy analytical workloads on very large graphs.

Key features:

• Property Graph data model with Cypher query language
• Embedded database - runs in-process with your application
• Columnar disk-based storage for analytical performance
• Strongly typed schema with explicit data types
• JSON support through the json extension
• Interoperability with Parquet, Arrow, DuckDB, and more

Components

Prompts

The server provides one prompt:

• ladybugdb-initial-prompt: A prompt to initialize a connection to LadybugDB and start working with it

Tools

The server offers one tool:

• query: Execute a Cypher query on the LadybugDB database
  • Inputs:
    • query (string, required): The Cypher query to execute

All interactions with LadybugDB are done through writing Cypher queries.

Result Limiting: Query results are automatically limited to prevent using up too much context:

• Maximum 1024 rows by default (configurable with --max-rows)
• Maximum 50,000 characters by default (configurable with --max-chars)
• Truncated responses include a note about truncation

Installation

Using pip (recommended)

pip install mcp-server-ladybug
mcp-server-ladybug --db-path :memory:

Note: Replace :memory: with a path like /path/to/local.lbdb to persist data to disk.

Using Docker

docker run -it --rm ghcr.io/ladybugdb/mcp-server-ladybug:latest --db-path :memory:

Note: Replace :memory: with a path like /path/to/local.lbdb to persist data to disk.

Using uvx

uvx mcp-server-ladybug --db-path :memory:

Note: Replace :memory: with a path like /path/to/local.lbdb to persist data to disk.

From source

git clone https://github.com/LadybugDB/mcp-server-ladybug.git
cd mcp-server-ladybug
uv pip install -e .
mcp-server-ladybug --db-path :memory:

Note: Replace :memory: with a path like /path/to/local.lbdb to persist data to disk.

Command Line Parameters

Parameter	Type	Default	Description
--transport	Choice	stdio	Transport type. Options: stdio, sse, stream
--port	Integer	8000	Port to listen on for sse and stream transport mode
--host	String	127.0.0.1	Host to bind the MCP server for sse and stream transport mode
--db-path	String	:memory:	Path to LadybugDB database file
--max-rows	Integer	1024	Maximum number of rows to return from queries
--max-chars	Integer	50000	Maximum number of characters in query results

Usage with Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-server-ladybug": {
      "command": "uvx",
      "args": [
        "mcp-server-ladybug",
        "--db-path",
        ":memory:"
      ]
    }
  }
}

Note: Replace :memory: with a path like /path/to/local.lbdb to persist data to disk.

Cypher Query Examples

Create a graph schema

CREATE NODE TABLE Person (id INT64 PRIMARY KEY, name STRING, age INT64);
CREATE NODE TABLE City (name STRING PRIMARY KEY, population INT64);
CREATE REL TABLE Follows (FROM Person TO Person, since INT64);
CREATE REL TABLE LivesIn (FROM Person TO City);

Import data from CSV

COPY Person FROM 'persons.csv';
COPY City FROM 'cities.csv';
COPY Follows FROM 'follows.csv';

Query relationships

MATCH (a:Person)-[:Follows]->(b:Person)
WHERE a.age > 25
RETURN a.name, b.name, a.age;

Use JSON data (requires json extension)

INSTALL json;
LOAD json;

CREATE NODE TABLE Product (id INT64 PRIMARY KEY, details JSON);
COPY Product FROM 'products.json';

MATCH (p:Product)
WHERE json_extract(p.details, '$.category') = 'electronics'
RETURN p.id, json_extract(p.details, '$.name') AS product_name;

Development

uv pip install -e .
python -m mcp_server_ladybug --db-path :memory:

Note: Replace :memory: with a path like /path/to/local.lbdb to persist data to disk.

License

MIT License