mcp -ladybug

The LadybugDB MCP Server provides a dedicated connector that enables AI assistants and IDEs to run Cypher queries against an embedded LadybugDB graph database. The server exposes a single prompt to initialize a connection and a tool named query that accepts a Cypher query string and returns results. By default results are restricted to protect context budgets (up to 1024 rows and 50,000 characters unless you override these limits with --max-rows and --max-chars). You can point clients and Claude Desktop integrations at the server using uvx, docker, or another supported launcher, and supply a local database path for persistence.

To use the query tool, send a Cypher query through the tool’s query input. The server will execute the Cypher against the LadybugDB embedded database and return a structured result set. If you need to create schema, import data, or run JSON operations, you can use Cypher commands such as CREATE, COPY, and INSTALL json; note that json extension must be loaded for JSON features. Transport options (stdio, sse, stream) can be chosen based on your integration, but default is stdio-compatible usage when launched via uvx or similar tooling.

Prerequisites:

• Python 3.9+ (or a compatible Python environment)
• uv/uvx tooling to run MCP servers (as shown below)
• Optional: Docker if you prefer containerized usage

Install flow (recommended, using uvx):

1. Install the MCP server via uvx and run with an in-memory or disk-backed database:

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

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

2. If you prefer to run from source, clone the repository and install in editable mode:

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.

3. Docker option (latest image):

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.

Tips and common issues:

• The server uses LadybugDB as an embedded graph database; ensure the --db-path points to a writable location, or use :memory: for ephemeral runs.
• You can adjust output size with --max-rows (default 1024) and --max-chars (default 50000).
• When using Claude Desktop, configure the mcpServers section to point to uvx with the appropriate --db-path arg, as shown in the README example.
• JSON data operations require loading the json extension in Cypher (INSTALL json; LOAD json;).
• If you encounter transport-related errors, verify that the selected transport (stdio, sse, stream) matches your integration channel and that the host/port settings align with your environment.