Gremlin

Connect AI agents like Claude, Cursor, and Windsurf to your graph databases!

An MCP (Model Context Protocol) server that enables AI assistants to interact with any Gremlin-compatible graph database through natural language. Query your data, discover schemas, analyze relationships, and manage graph data using simple conversations.

- 🔍"What's the structure of my graph?"- Automatic schema discovery
- 📊"Show me all users over 30 and their connections"- Complex graph queries
- 🔗"Find the shortest path between Alice and Bob"- Relationship analysis
- 📈"Give me graph statistics and metrics"- Data insights
- 📥"Import this GraphSON data"- Data loading
- 📤"Export user data as CSV"- Data extraction
- 🧠Smart enum discovery- AI learns your data's valid values automatically

Your AI assistant gets access to these powerful tools:

# The npx command will automatically install the package if needed # No separate installation step required

# Clone and setup git clone https://github.com/kpritam/gremlin-mcp.git cd gremlin-mcp npm install npm run build

Add this to your MCP client configuration:

Using the published package (recommended):

{ "mcpServers": { "gremlin": { "command": "npx", "args": ["@kpritam/gremlin-mcp"], "env": { "GREMLIN_ENDPOINT": "localhost:8182", "LOG_LEVEL": "info" } } } }

{ "mcpServers": { "gremlin": { "command": "node", "args": ["/path/to/gremlin-mcp/dist/server.js"], "env": { "GREMLIN_ENDPOINT": "localhost:8182", "LOG_LEVEL": "info" } } } }

{ "mcpServers": { "gremlin": { "command": "npx", "args": ["@kpritam/gremlin-mcp"], "env": { "GREMLIN_ENDPOINT": "your-server.com:8182", "GREMLIN_USERNAME": "your-username", "GREMLIN_PASSWORD": "your-password", "GREMLIN_USE_SSL": "true" } } } }

Make sure your Gremlin-compatible database is running:

# For Apache TinkerPop Gremlin Server ./bin/gremlin-server.sh start # Or using Docker docker run -p 8182:8182 tinkerpop/gremlin-server

"Can you check if my graph database is connected and show me its schema?"

You ask:"What's the structure of my graph database?"

AI response:The AI callsget_graph_schemaand tells you about your node types, edge types, and how they're connected.

You ask:"Show me all people over 30 and their relationships"

AI response:The AI executesg.V().hasLabel('person').has('age', gt(30)).out().path()and explains the results in natural language.

You ask:"Give me some statistics about my graph"

AI response:The AI runs multiple queries to count nodes, edges, and analyze the distribution, then presents a summary.

You ask:"Load this GraphSON data into my database"

AI response:The AI usesimport_graph_datato process your data in batches and reports the import status.

Why this matters:AI agents work best when they know the exact valid values for properties. Instead of guessing or making invalid queries, they can use precise, real values from your data.

One of the most powerful features of this MCP server isAutomatic Enum Discovery- it intelligently analyzes your graph data to discover valid property values and provides them as enums to AI agents.

AI: "I see this vertex has a 'status' property of type 'string'... Let me try querying with status='active'" Result: ❌ No results (actual values are 'CONFIRMED', 'PENDING', 'CANCELLED')

AI: "I can see the 'status' property has these exact values: ['CONFIRMED', 'PENDING', 'CANCELLED', 'WAITLISTED'] Let me query with status='CONFIRMED'" Result: ✅ Perfect results using real data values

The server automatically scans your graph properties and:
- Identifies Low-Cardinality Properties- Properties with a reasonable number of distinct values
- Extracts Real Values- Samples actual data from your graph
- Provides as Enums- Includes valid values in the schema for AI agents

{ "name": "bookingStatus", "type": ["string"], "cardinality": "single", "enum": ["CONFIRMED", "PENDING", "CANCELLED", "WAITLISTED"], "sample_values": ["CONFIRMED", "PENDING"] }

- 🎯 Accurate Queries- AI uses real values instead of guessing
- ⚡ Faster Results- No trial-and-error with invalid values
- 🧠 Better Understanding- AI learns your data vocabulary
- 📊 Smarter Analytics- Enables grouping and filtering with actual categories

Fine-tune enum discovery to match your data:

# Enable/disable enum discovery GREMLIN_ENUM_DISCOVERY_ENABLED="true" # Default: true # Control what gets detected as enum GREMLIN_ENUM_CARDINALITY_THRESHOLD="10" # Max distinct values for enum (default: 10) # Exclude specific properties GREMLIN_ENUM_PROPERTY_BLACKLIST="id,uuid,timestamp,createdAt,updatedAt" # Schema optimization GREMLIN_SCHEMA_MAX_ENUM_VALUES="10" # Limit enum values shown (default: 10) GREMLIN_SCHEMA_INCLUDE_SAMPLE_VALUES="false" # Reduce schema size (default: false)

Some properties should never be treated as enums:

- High-cardinalityproperties (> threshold unique values)
- Numeric IDsandUUIDs
- Timestampsanddates
- Long textfields

# Exclude specific properties by name GREMLIN_ENUM_PROPERTY_BLACKLIST="userId,sessionId,description,notes,content"

- id,uuid,guid- Unique identifiers
- timestamp,createdAt,updatedAt,lastModified- Time fields
- description,notes,comment,content,text- Free text fields
- email,url,phone,address- Personal/contact data
- hash,token,key,secret- Security-related fields

{ "orderStatus": { "enum": ["PENDING", "PROCESSING", "SHIPPED", "DELIVERED", "CANCELLED"] }, "productCategory": { "enum": ["ELECTRONICS", "CLOTHING", "BOOKS", "HOME", "SPORTS"] }, "paymentMethod": { "enum": ["CREDIT_CARD", "PAYPAL", "BANK_TRANSFER", "CRYPTO"] } }

{ "relationshipType": { "enum": ["FRIEND", "FAMILY", "COLLEAGUE", "ACQUAINTANCE"] }, "privacyLevel": { "enum": ["PUBLIC", "FRIENDS", "PRIVATE"] }, "accountStatus": { "enum": ["ACTIVE", "SUSPENDED", "DEACTIVATED"] } }

GREMLIN_ENUM_CARDINALITY_THRESHOLD="5" # Stricter enum detection GREMLIN_SCHEMA_MAX_ENUM_VALUES="5" # Fewer values in schema

GREMLIN_ENUM_CARDINALITY_THRESHOLD="25" # More permissive detection GREMLIN_SCHEMA_MAX_ENUM_VALUES="20" # Show more enum values

GREMLIN_ENUM_DISCOVERY_ENABLED="false" # Disable for faster schema loading GREMLIN_SCHEMA_INCLUDE_SAMPLE_VALUES="false" # Minimal schema size

This intelligent enum discovery transforms how AI agents interact with your graph data, making queries more accurate and insights more meaningful! 🎯

Works with any Gremlin-compatible graph database:

# Required GREMLIN_ENDPOINT="localhost:8182" # Optional GREMLIN_USE_SSL="true" # Enable SSL/TLS GREMLIN_USERNAME="username" # Authentication GREMLIN_PASSWORD="password" # Authentication GREMLIN_IDLE_TIMEOUT="300" # Connection timeout in seconds (default: 300) LOG_LEVEL="info" # Logging level: error, warn, info, debug

# Schema and performance tuning GREMLIN_ENUM_DISCOVERY_ENABLED="true" # Enable smart enum detection (default: true) GREMLIN_ENUM_CARDINALITY_THRESHOLD="10" # Max distinct values for enum detection (default: 10) GREMLIN_ENUM_PROPERTY_BLACKLIST="id,timestamp" # Exclude specific properties from enum detection GREMLIN_SCHEMA_INCLUDE_SAMPLE_VALUES="false" # Include sample values in schema (default: false) GREMLIN_SCHEMA_MAX_ENUM_VALUES="10" # Limit enum values shown (default: 10) GREMLIN_SCHEMA_INCLUDE_COUNTS="true" # Include vertex/edge counts in schema (default: true)

⚠️ Important:This server is designed for development and trusted environments.

- Basic input sanitization (advanced injection protection in development)
- No connection pooling or rate limiting
- All Gremlin syntax is permitted
- No audit logging for security monitoring

- 🔒 Use behind a firewall in production
- 🔑 Enable strong authentication on your Gremlin server
- 📊 Monitor query patterns and resource usage
- 🛡️ Consider a query proxy for additional security controls
- 🔄 Keep dependencies updated

- "Schema cache failed"- Server couldn't discover graph structure (empty database?)
- "Invalid query syntax"- Gremlin query has syntax errors
- "Timeout"- Query took too long, checkGREMLIN_IDLE_TIMEOUT

# Test connection curl -f http://localhost:8182/ # Check server logs tail -f logs/gremlin-mcp.log # Verify schema endpoint curl http://localhost:8182/gremlin

The following sections are for developers who want to contribute to or modify the server.

# Clone and install git clone https://github.com/kpritam/gremlin-mcp.git cd gremlin-mcp npm install # Development with hot reload npm run dev # Run tests npm test npm run test:coverage npm run test:watch # Integration tests (requires running Gremlin server) GREMLIN_ENDPOINT=localhost:8182/g npm run test:it # All tests together (unit + integration) npm test && npm run test:it

- Full Type Safety: TypeScript + Effect functional programming patterns
- Effect-based Architecture: Uses Effect.ts for composable, type-safe operations
- Service-Oriented Design: Dependencies managed through Effect's Context.Tag patterns
- Layer-Based Composition: Application built using Effect.Layer for dependency resolution
- Comprehensive Testing: Unit + Integration tests with Effect testing patterns
- Error Handling: Effect-based error management with custom error types

src/ ├── server.ts # Effect-based MCP server with graceful startup/shutdown ├── config.ts # Effect.Config-based configuration validation ├── constants.ts # Application constants integrated with Effect configuration ├── gremlin/ │ ├── service.ts # GremlinService using Effect.Context.Tag pattern │ ├── schema-service.ts # SchemaService with Effect dependency injection │ └── types.ts # TypeScript types and schemas ├── handlers/ # Effect-based MCP request handlers │ ├── tools.ts # Effect-based tool handlers │ ├── resources.ts # Effect-based resource handlers │ └── effect-runtime-bridge.ts # ManagedRuntime container for Effect execution └── utils/ # Effect-based utility modules ├── data-operations.ts # Effect-based graph data import/export operations ├── result-parser.ts # Gremlin result parsing with metadata extraction └── type-guards.ts # Runtime type checking functions

The server implements intelligent schema discovery with enumeration detection:

// Property with detected enum values { "name": "status", "type": ["string"], "cardinality": "single", "enum": ["Confirmed", "Pending", "Cancelled", "Waitlisted"] }

- Follow the rules inRULES.md
- Runnpm run validatebefore committing
- Add tests for new functionality
- Update documentation for user-facing changes
- Ensure all tests pass

- Unit Tests(tests/): Individual component testing

- Component isolation with comprehensive mocking
- Type safety validation with Zod schemas
- Fast execution without external dependencies

- Real Gremlin server connections via Docker
- End-to-end MCP protocol validation
- Database operations and query execution

- Unit tests run on every commit
- Integration tests run with Docker Gremlin server
- Both required for releases

MIT License - feel free to use in your projects!

Questions?Check thetroubleshooting guideoropen an issue.

Connects to Neo4j graph databases with ability to use GDS functions ( when available), a read only mode , and set the sample size for schema detection