Amazon Neptune MCP Server

1.0.16 verified Fri May 01 auth: no python

An MCP (Model Context Protocol) server for Amazon Neptune that provides tools to fetch status, schema, and execute queries using openCypher, Gremlin, and SPARQL for Neptune Database, and openCypher for Neptune Analytics. Current version 1.0.16, requires Python >=3.10.

pip install awslabs-amazon-neptune-mcp-server

Common errors

error ModuleNotFoundError: No module named 'neptune_mcp' ↓

cause Package not installed or wrong import path.

fix

Run 'pip install awslabs-amazon-neptune-mcp-server' and import 'neptune_mcp'.

error botocore.exceptions.NoCredentialsError: Unable to locate credentials ↓

cause AWS credentials not configured.

fix

Configure AWS credentials via environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) or IAM role.

error ConnectionError: Could not connect to Neptune endpoint: ... ↓

cause Endpoint or port is incorrect, or network not accessible.

fix

Verify the Neptune endpoint and port (8182 for Database, 8183 for Analytics). Ensure security groups allow inbound traffic on the port.

Warnings

deprecated The 'gremlin' extra (gremlinpython) is no longer maintained; consider using openCypher or SPARQL for queries. ↓

fix Use openCypher by default; set connection_type to 'database' and query language to 'openCypher'.

gotcha The server requires explicit AWS credentials (via environment variables, IAM roles, or ~/.aws/credentials). Missing credentials result in silent failures. ↓

fix Set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN (if using temporary credentials) as environment variables.

gotcha Port 8182 is hardcoded as default for Neptune Database; Neptune Analytics uses port 8183. Using wrong port leads to connection timeout. ↓

fix Set NEPTUNE_PORT environment variable or pass port parameter explicitly.

Install

pip install awslabs-amazon-neptune-mcp-server[gremlin]

pip install awslabs-amazon-neptune-mcp-server[all]

Imports

NeptuneMCPServer

from neptune_mcp.server import NeptuneMCPServer

Main server class

Quickstart

Initialize and run the Neptune MCP server with environment variables for configuration.

from neptune_mcp.server import NeptuneMCPServer

# Replace with your Neptune endpoint and port
endpoint = os.environ.get('NEPTUNE_ENDPOINT', 'your-neptune-endpoint')
port = int(os.environ.get('NEPTUNE_PORT', '8182'))

server = NeptuneMCPServer(
    endpoint=endpoint,
    port=port,
    region=os.environ.get('AWS_REGION', 'us-east-1'),
    # Optional: specify connection type
    connection_type='database',  or 'analytics'
)
server.run()