AWS Labs Amazon Neptune MCP Server

An Amazon Neptune MCP server that allows for fetching status, schema, and querying using openCypher and Gremlin for Neptune Database and openCypher for Neptune Analytics.

Features

The Amazon Neptune MCP Server provides the following capabilities:

Run Queries: Execute openCypher and/or Gremlin queries against the configured database
Schema: Get the schema in the configured graph as a text string
Status: Find if the graph is "Available" or "Unavailable" to your server. This is useful in helping to ensure that the graph is connected.

AWS Requirements

AWS CLI Configuration: You must have the AWS CLI configured with credentials and an AWS_PROFILE that has access to Amazon Neptune
Amazon Neptune: You must have at least one Amazon Neptune Database or Amazon Neptune Analytics graph.
IAM Permissions: Your IAM role/user must have appropriate permissions to:
- Access Amazon Neptune
- Query Amazon Neptune
Access: The location where you are running the server must have access to the Amazon Neptune instance. Neptune Database resides in a private VPC so access into the private VPC. Neptune Analytics can be access either using a public endpoint, if configured, or the access will be needed to the private endpoint.

Note: This server will run any query sent to it, which could include both mutating and read-only actions. Properly configuring the permissions of the role to allow/disallow specific data plane actions as specified here:

Prerequisites

Install uv from Astral or the GitHub README
Install Python using uv python install 3.10

Installation

Below is an example of how to configure your MCP client, although different clients may require a different format.

{
  "mcpServers": {
    "Neptune Query": {
      "command": "uvx",
      "args": ["awslabs.amazon-neptune-mcp-server@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "INFO",
        "NEPTUNE_ENDPOINT": "<INSERT NEPTUNE ENDPOINT IN FORMAT SPECIFIED BELOW>"
      }
    }
  }
}

Docker Configuration

After building with docker build -t awslabs/amazon-neptune-mcp-server .:

{
  "mcpServers": {
    "awslabs.amazon-neptune-mcp-server": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "awslabs/amazon-neptune-mcp-server"
        ],
        "env": {
        "FASTMCP_LOG_LEVEL": "INFO",
        "NEPTUNE_ENDPOINT": "<INSERT NEPTUNE ENDPOINT IN FORMAT SPECIFIED BELOW>"
        },
        "disabled": false,
        "autoApprove": []
    }
  }
}

When specifying the Neptune Endpoint the following formats are expected:

For Neptune Database: neptune-db://<Cluster Endpoint>

For Neptune Analytics: neptune-graph://<graph identifier>

Features

The Amazon Neptune MCP Server provides the following capabilities:

Run Queries: Execute openCypher and/or Gremlin queries against the configured database

Schema: Get the schema in the configured graph as a text string

Status: Find if the graph is "Available" or "Unavailable" to your server. This is useful in helping to ensure that the graph is connected.

AWS Requirements

AWS CLI Configuration: You must have the AWS CLI configured with credentials and an AWS_PROFILE that has access to Amazon Neptune

Amazon Neptune: You must have at least one Amazon Neptune Database or Amazon Neptune Analytics graph.

IAM Permissions: Your IAM role/user must have appropriate permissions to:

Access Amazon Neptune
Query Amazon Neptune

Access: The location where you are running the server must have access to the Amazon Neptune instance. Neptune Database resides in a private VPC so access into the private VPC. Neptune Analytics can be access either using a public endpoint, if configured, or the access will be needed to the private endpoint.

Installation

Below is an example of how to configure your MCP client, although different clients may require a different format.

{ "mcpServers": { "Neptune Query": { "command": "uvx", "args": ["awslabs.amazon-neptune-mcp-server@latest"], "env": { "FASTMCP_LOG_LEVEL": "INFO", "NEPTUNE_ENDPOINT": "<INSERT NEPTUNE ENDPOINT IN FORMAT SPECIFIED BELOW>" } } } }

Docker Configuration

After building with docker build -t awslabs/amazon-neptune-mcp-server .:

{ "mcpServers": { "awslabs.amazon-neptune-mcp-server": { "command": "docker", "args": [ "run", "--rm", "-i", "awslabs/amazon-neptune-mcp-server" ], "env": { "FASTMCP_LOG_LEVEL": "INFO", "NEPTUNE_ENDPOINT": "<INSERT NEPTUNE ENDPOINT IN FORMAT SPECIFIED BELOW>" }, "disabled": false, "autoApprove": [] } } }

When specifying the Neptune Endpoint the following formats are expected:

For Neptune Database: neptune-db://<Cluster Endpoint>

For Neptune Analytics: neptune-graph://<graph identifier>