PuppyGraph MCP Server

Model Context Protocol (MCP) server for PuppyGraph, allowing Claude to query the graph using Gremlin and Cypher through Claude Desktop.

Features

• Connect to PuppyGraph instances using both Neo4j Bolt protocol (for Cypher) and WebSocket (for Gremlin)
• Query graph data using both Gremlin and Cypher query languages
• Retrieve graph structure and schema information from multiple endpoints
• Works with Claude Desktop and other MCP-compatible interfaces
• Robust fallback mechanisms with multiple connection approaches
• Graceful degradation with sample data when connections fail

Prerequisites

• Node.js 18+
• A running PuppyGraph instance (or fallback mode for testing)

Installation

1. Clone this repository
2. Install dependencies:

npm install

3. Build the project:

npm run build

Usage

Start the server:

npm start

Using environment variables:

# Connect to a specific PuppyGraph instance
PUPPYGRAPH_URL=bolt://your-puppygraph-server:7687 PUPPYGRAPH_USERNAME=neo4j PUPPYGRAPH_PASSWORD=your-password npm start

# Connect to both Neo4j and Gremlin endpoints
PUPPYGRAPH_URL=bolt://your-neo4j-server:7687 PUPPYGRAPH_GREMLIN_URL=ws://your-gremlin-server:8182/gremlin npm start

Claude Desktop Configuration

Note: if you're using Claude Desktop to access the tools, make sure that you don't have the server running in a separate terminal. Claude Desktop will start the server itself based on the commands in the MCP config below.

You can set up the MCP server in your Claude Desktop configuration and OPTIONALLY include environment variables directly in the config:

{
  "mcpServers": {
    "puppygraph": {
      "command": "node",
      "args": [
        "/path/to/puppygraph-mcp/build/index.js"
      ],
      "env": {
        "PUPPYGRAPH_URL": "bolt://your-neo4j-server:7687",
        "PUPPYGRAPH_USERNAME": "neo4j",
        "PUPPYGRAPH_PASSWORD": "your-password",
        "PUPPYGRAPH_DATABASE": "your-database",
        "PUPPYGRAPH_GREMLIN_URL": "ws://your-gremlin-server:8182/gremlin",
        "PUPPYGRAPH_GREMLIN_USERNAME": "your-username",
        "PUPPYGRAPH_GREMLIN_PASSWORD": "your-password"
      }
    }
  }
}

Replace the paths and connection details with your specific values. The env section allows you to specify all environment variables directly in the configuration file.

Available Tools

• puppygraph_query: Execute Gremlin or Cypher queries against PuppyGraph
• puppygraph_schema: Get schema and structure information about the graph
• puppygraph_status: Check PuppyGraph connection status

Each tool is also available with an mcp__ prefix (e.g., mcp__puppygraph_query) for compatibility with certain LLM platforms.

Environment Variables

Graph Database Connections

Neo4j Connection (Cypher queries)

• PUPPYGRAPH_URL: URL of the PuppyGraph Neo4j endpoint (default: bolt://localhost:7687)
• PUPPYGRAPH_USERNAME: Username for PuppyGraph Neo4j authentication (default: neo4j)
• PUPPYGRAPH_PASSWORD: Password for PuppyGraph Neo4j authentication (default: password)
• PUPPYGRAPH_DATABASE: Name of the database to connect to (default: "")

Gremlin Connection (Gremlin queries)

• PUPPYGRAPH_GREMLIN_URL: URL of the PuppyGraph Gremlin endpoint (default: ws://localhost:8182/gremlin)
• PUPPYGRAPH_GREMLIN_USERNAME: Username for PuppyGraph Gremlin authentication (default: puppygraph)
• PUPPYGRAPH_GREMLIN_PASSWORD: Password for PuppyGraph Gremlin authentication (default: puppygraph123)
• PUPPYGRAPH_GREMLIN_TRAVERSAL_SOURCE: Traversal source name (default: g)

Schema API Connection

• PUPPYGRAPH_SCHEMA_URL: URL of the PuppyGraph schema endpoint (default: http://localhost:8081/schemajson)
• PUPPYGRAPH_SCHEMA_USERNAME: Username for PuppyGraph schema API authentication (default: puppygraph)
• PUPPYGRAPH_SCHEMA_PASSWORD: Password for PuppyGraph schema API authent

... View full README on GitHub