Skip to content

AI Integrations

PuppyGraph can be the live graph backend for AI tools. Your agent can inspect the graph schema, generate Cypher or Gremlin, run the query against current source data, and answer from returned rows.

Choose a starting point

Before you integrate

This page assumes you already have a running PuppyGraph instance and an active graph schema. To prepare that environment, use:

The examples below use PuppyGraph's default local ports: 8081 for the Web UI and REST API, 7687 for openCypher over Bolt, and 8182 for Gremlin WebSocket.

Run the MCP server

Use the PuppyGraph MCP Server when you want Claude Desktop or another MCP-compatible client to call PuppyGraph tools directly. The server connects to PuppyGraph through Bolt for openCypher, Gremlin WebSocket for traversals, and the REST API for schema metadata.

The server exposes a small tool surface:

  • puppygraph_query runs Cypher or Gremlin against PuppyGraph.
  • puppygraph_schema returns graph labels, relationships, and properties.

  • puppygraph_status checks that the server can reach PuppyGraph.

  • Clone and build the open-source MCP server:

git clone https://github.com/puppygraph/puppygraph-mcp-server.git
cd puppygraph-mcp-server
npm install
npm run build
  1. Start it against a local PuppyGraph instance:
PUPPYGRAPH_URL=bolt://localhost:7687 \
PUPPYGRAPH_USERNAME=puppygraph \
PUPPYGRAPH_PASSWORD=puppygraph123 \
PUPPYGRAPH_GREMLIN_URL=ws://localhost:8182/gremlin \
npm start
  1. Configure your MCP client to launch the built server. For Claude Desktop, follow the configuration example in the MCP server README.

Run the Python chatbot demo

Use the Python chatbot demo when you want a standalone application that turns natural language into Cypher and shows the result in a Gradio UI.

The demo lives in the PuppyGraph Python repository. It includes a schema viewer, graph statistics, a text-to-Cypher RAG system, and an MCP server implementation for query execution and schema lookup.

git clone https://github.com/puppygraph/puppygraph-python.git
cd puppygraph-python/apps/chatbot
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Edit .env with:

  • ANTHROPIC_API_KEY.
  • PUPPYGRAPH_BOLT_URI, default bolt://localhost:7687.
  • PUPPYGRAPH_HTTP_URI, default http://localhost:8081.
  • PUPPYGRAPH_USERNAME and PUPPYGRAPH_PASSWORD.

Then start the app:

python gradio_app.py

Open http://localhost:7860 and ask a graph question, for example:

What types of nodes exist?

Build your own query tool

For most application agents, use openCypher over Bolt. Many AI frameworks already know how to work with Neo4j-compatible drivers, and Cypher is easier to inspect than a long traversal string.

pip install neo4j

from neo4j import GraphDatabase


def run_cypher(query: str, parameters: dict | None = None) -> list[dict]:
    driver = GraphDatabase.driver(
        "bolt://localhost:7687",
        auth=("puppygraph", "puppygraph123"),
    )
    try:
        records, _, _ = driver.execute_query(
            query,
            parameters or {},
        )
        return [record.data() for record in records]
    finally:
        driver.close()

Give the model a short contract for this tool:

Use this tool only for read-only graph queries.
Always include LIMIT unless the query is an aggregate count.
Answer only from returned rows.
If the result is empty, explain which labels and relationships were queried.

Use Gremlin when your application already models traversal steps directly:

pip install gremlinpython

from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection
from gremlin_python.process.anonymous_traversal import traversal


connection = DriverRemoteConnection(
    "ws://localhost:8182/gremlin",
    "g",
    username="puppygraph",
    password="puppygraph123",
)

try:
    g = traversal().with_remote(connection)
    rows = g.V().limit(20).value_map(True).to_list()
finally:
    connection.close()

Keep the integration safe

  • Use a service account for the application. See Role-Based Access Control.
  • Apply row-level security when users should see different slices of the graph.
  • Keep generated queries out of INFO logs. Use debug-level logging or a controlled audit path for query diagnostics.
  • Keep schema and catalog mutations behind an explicit administrative approval flow.
  • Store the user question, generated query, and returned rows together when debugging AI answers.