aura-manager - add security middleware to aura server (#171)

Author: a-s-g93

servers/mcp-neo4j-cloud-aura-api/CHANGELOG.md

@@ -9,6 +9,9 @@
 
 ### Added
 * Add tool annotations to tools to better describe their effects
+* Add security middleware (CORS and TrustedHost protection) for HTTP transport
+* Add `--allow-origins` and `--allowed-hosts` command line arguments
+* Add security environment variables: `NEO4J_MCP_SERVER_ALLOW_ORIGINS` and `NEO4J_MCP_SERVER_ALLOWED_HOSTS`
 
 ## v0.3.0
 

servers/mcp-neo4j-cloud-aura-api/Dockerfile

@@ -26,6 +26,8 @@ ENV NEO4J_TRANSPORT="stdio"
 ENV NEO4J_MCP_SERVER_HOST="127.0.0.1"
 ENV NEO4J_MCP_SERVER_PORT=8000
 ENV NEO4J_MCP_SERVER_PATH="/mcp/"
+ENV NEO4J_MCP_SERVER_ALLOW_ORIGINS=""
+ENV NEO4J_MCP_SERVER_ALLOWED_HOSTS="localhost,127.0.0.1"
 
 # Command to run the server using the package entry point
 CMD ["sh", "-c", "mcp-neo4j-aura-manager"]

servers/mcp-neo4j-cloud-aura-api/Makefile

@@ -1,3 +1,9 @@
+.PHONY: docker-local-build-run install-dev test-unit test-integration test-http test-all all
+
+docker-local-build-run:
+	docker build -t mcp-neo4j-aura-manager .
+	docker run -p 8000:8000 mcp-neo4j-aura-manager:latest
+
 install-dev:
 	uv sync
 

servers/mcp-neo4j-cloud-aura-api/README.md

@@ -183,6 +183,8 @@ export NEO4J_TRANSPORT=http
 export NEO4J_MCP_SERVER_HOST=127.0.0.1
 export NEO4J_MCP_SERVER_PORT=8080
 export NEO4J_MCP_SERVER_PATH=/api/mcp/
+export NEO4J_MCP_SERVER_ALLOWED_HOSTS="localhost,127.0.0.1"
+export NEO4J_MCP_SERVER_ALLOW_ORIGINS="http://localhost:3000"
 mcp-neo4j-aura-manager
 ```
 
@@ -191,9 +193,183 @@ mcp-neo4j-aura-manager
 The server supports three transport modes:
 
 - **STDIO** (default): Standard input/output for local tools and Claude Desktop
-- **SSE**: Server-Sent Events for web-based deployments  
+- **SSE**: Server-Sent Events for web-based deployments
 - **HTTP**: Streamable HTTP for modern web deployments and microservices
 
+## 🔒 Security Protection
+
+The server includes comprehensive security protection with **secure defaults** that protect against common web-based attacks while preserving full MCP functionality when using HTTP transport.
+
+### 🛡️ DNS Rebinding Protection
+
+**TrustedHost Middleware** validates Host headers to prevent DNS rebinding attacks:
+
+**Secure by Default:**
+- Only `localhost` and `127.0.0.1` hosts are allowed by default
+- Malicious websites cannot trick browsers into accessing your local server
+
+**Environment Variable:**
+```bash
+export NEO4J_MCP_SERVER_ALLOWED_HOSTS="example.com,www.example.com"
+```
+
+### 🌐 CORS Protection
+
+**Cross-Origin Resource Sharing (CORS)** protection blocks browser-based requests by default:
+
+**Environment Variable:**
+```bash
+export NEO4J_MCP_SERVER_ALLOW_ORIGINS="https://example.com,https://example.com"
+```
+
+### 🔧 Complete Security Configuration
+
+**Development Setup:**
+```bash
+mcp-neo4j-aura-manager --transport http \
+  --allowed-hosts "localhost,127.0.0.1" \
+  --allow-origins "http://localhost:3000"
+```
+
+**Production Setup:**
+```bash
+mcp-neo4j-aura-manager --transport http \
+  --allowed-hosts "example.com,www.example.com" \
+  --allow-origins "https://example.com,https://example.com"
+```
+
+### 🚨 Security Best Practices
+
+**For `allow_origins`:**
+- Be specific: `["https://example.com", "https://example.com"]`
+- Never use `"*"` in production with credentials
+- Use HTTPS origins in production
+
+**For `allowed_hosts`:**
+- Include your actual domain: `["example.com", "www.example.com"]`
+- Include localhost only for development
+- Never use `"*"` unless you understand the risks
+
+
+## 🐳 Docker Deployment
+
+The Neo4j Aura Manager MCP server can be deployed using Docker for remote deployments. Docker deployment should use HTTP transport for web accessibility. In order to integrate this deployment with applications like Claude Desktop, you will have to use a proxy in your MCP configuration such as `mcp-remote`.
+
+### 🐳 Using with Docker for Claude Desktop
+
+Here we use the Docker Hub hosted Aura Manager MCP server image with stdio transport for use with Claude Desktop.
+
+**Config details:**
+* `-i`: Interactive mode - keeps STDIN open for stdio transport communication
+* `--rm`: Automatically remove container when it exits (cleanup)
+* `-p 8000:8000`: Port mapping - maps host port 8000 to container port 8000
+* `NEO4J_TRANSPORT=stdio`: Uses stdio transport for Claude Desktop compatibility
+* `NEO4J_AURA_CLIENT_ID` and `NEO4J_AURA_CLIENT_SECRET`: Your Aura API credentials
+
+```json
+{
+  "mcpServers": {
+    "neo4j-aura": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-p",
+        "8000:8000",
+        "-e", "NEO4J_AURA_CLIENT_ID=your-client-id",
+        "-e", "NEO4J_AURA_CLIENT_SECRET=your-client-secret",
+        "-e", "NEO4J_TRANSPORT=stdio",
+        "mcp/neo4j-aura-manager:latest"
+      ]
+    }
+  }
+}
+```
+
+### 📦 Using Your Built Image
+
+After building locally with `docker build -t mcp-neo4j-aura-manager:latest .`:
+
+```bash
+# Build the image
+docker build -t mcp-neo4j-aura-manager:<version> .
+
+# Run with http transport (default for Docker)
+docker run --rm -p 8000:8000 \
+  -e NEO4J_AURA_CLIENT_ID="your-client-id" \
+  -e NEO4J_AURA_CLIENT_SECRET="your-client-secret" \
+  -e NEO4J_TRANSPORT="http" \
+  -e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
+  -e NEO4J_MCP_SERVER_PORT="8000" \
+  -e NEO4J_MCP_SERVER_PATH="/mcp/" \
+  mcp-neo4j-aura-manager:<version>
+
+# Run with security middleware for production
+docker run --rm -p 8000:8000 \
+  -e NEO4J_AURA_CLIENT_ID="your-client-id" \
+  -e NEO4J_AURA_CLIENT_SECRET="your-client-secret" \
+  -e NEO4J_TRANSPORT="http" \
+  -e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
+  -e NEO4J_MCP_SERVER_PORT="8000" \
+  -e NEO4J_MCP_SERVER_PATH="/mcp/" \
+  -e NEO4J_MCP_SERVER_ALLOWED_HOSTS="example.com,www.example.com" \
+  -e NEO4J_MCP_SERVER_ALLOW_ORIGINS="https://example.com" \
+  mcp-neo4j-aura-manager:<version>
+```
+
+### 🔧 Environment Variables
+
+| Variable                           | Default                                 | Description                                        |
+| ---------------------------------- | --------------------------------------- | -------------------------------------------------- |
+| `NEO4J_AURA_CLIENT_ID`             | _(none)_                                | Neo4j Aura API Client ID                          |
+| `NEO4J_AURA_CLIENT_SECRET`         | _(none)_                                | Neo4j Aura API Client Secret                      |
+| `NEO4J_TRANSPORT`                  | `stdio` (local), `http` (remote)        | Transport protocol (`stdio`, `http`, or `sse`)     |
+| `NEO4J_MCP_SERVER_HOST`            | `127.0.0.1` (local)                     | Host to bind to                                    |
+| `NEO4J_MCP_SERVER_PORT`            | `8000`                                  | Port for HTTP/SSE transport                        |
+| `NEO4J_MCP_SERVER_PATH`            | `/mcp/`                                 | Path for accessing MCP server                      |
+| `NEO4J_MCP_SERVER_ALLOW_ORIGINS`   | _(empty - secure by default)_           | Comma-separated list of allowed CORS origins       |
+| `NEO4J_MCP_SERVER_ALLOWED_HOSTS`   | `localhost,127.0.0.1`                   | Comma-separated list of allowed hosts (DNS rebinding protection) |
+
+### 🌐 SSE Transport for Legacy Web Access
+
+When using SSE transport (for legacy web clients), the server exposes an HTTP endpoint:
+
+```bash
+# Start the server with SSE transport
+docker run -d -p 8000:8000 \
+  -e NEO4J_AURA_CLIENT_ID="your-client-id" \
+  -e NEO4J_AURA_CLIENT_SECRET="your-client-secret" \
+  -e NEO4J_TRANSPORT="sse" \
+  -e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
+  -e NEO4J_MCP_SERVER_PORT="8000" \
+  --name neo4j-aura-mcp-server \
+  mcp-neo4j-aura-manager:latest
+
+# Test the SSE endpoint
+curl http://localhost:8000/sse
+
+# Use with MCP Inspector
+npx @modelcontextprotocol/inspector http://localhost:8000/sse
+```
+
+### 🔗 Claude Desktop Integration with Docker
+
+For Claude Desktop integration with a Dockerized server using http transport:
+
+```json
+{
+  "mcpServers": {
+    "neo4j-aura-docker": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote@latest", "http://localhost:8000/mcp/"]
+    }
+  }
+}
+```
+
+**Note**: First start your Docker container with HTTP transport, then Claude Desktop can connect to it via the HTTP endpoint and proxy server like `mcp-remote`.
+
 ## 📝 Usage Examples
 
 ### 🔍 Give overview over my tenants
@@ -245,20 +421,6 @@ source .venv/bin/activate  # On Unix/macOS
 uv pip install -e ".[dev]"
 ```
 
-### 🐳 Docker
-
-Build and run the Docker container:
-
-```bash
-# Build the image
-docker build -t mcp-neo4j-aura-manager:<version> .
-
-# Run the container
-docker run -e NEO4J_AURA_CLIENT_ID="your-client-id" \
-          -e NEO4J_AURA_CLIENT_SECRET="your-client-secret" \
-          mcp-neo4j-aura-manager:<version>
-```
-
 ## 📄 License
 
 This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

servers/mcp-neo4j-cloud-aura-api/pyproject.toml

@@ -7,6 +7,7 @@ requires-python = ">=3.10"
 dependencies = [
     "fastmcp>=2.0.0",
     "requests>=2.31.0",
+    "starlette>=0.40.0",
 ]
 
 [build-system]
@@ -28,3 +29,8 @@ mcp-neo4j-aura-manager = "mcp_neo4j_aura_manager:main"
 pythonpath = [
   "src"
 ]
+asyncio_mode = "strict"
+asyncio_default_fixture_loop_scope = "session"
+markers = [
+    "middleware: marks tests as middleware security tests that don't require Aura credentials"
+]

servers/mcp-neo4j-cloud-aura-api/src/mcp_neo4j_aura_manager/__init__.py

@@ -22,21 +22,40 @@ def main():
     parser.add_argument("--server-host", default=None, help="Server host")
     parser.add_argument("--server-port", default=None, help="Server port")
     parser.add_argument("--server-path", default=None, help="Server path")
+    parser.add_argument(
+        "--allow-origins",
+        default=None,
+        help="Allow origins for remote servers (comma-separated list)",
+    )
+    parser.add_argument(
+        "--allowed-hosts",
+        default=None,
+        help="Allowed hosts for DNS rebinding protection on remote servers(comma-separated list)",
+    )
 
     args = parser.parse_args()
 
     if not args.client_id or not args.client_secret:
         logger.error("Client ID and Client Secret are required. Provide them as arguments or environment variables.")
         sys.exit(1)
 
+    # Parse security arguments
+    allow_origins_str = args.allow_origins or os.getenv("NEO4J_MCP_SERVER_ALLOW_ORIGINS", "")
+    allow_origins = [origin.strip() for origin in allow_origins_str.split(",") if origin.strip()] if allow_origins_str else []
+
+    allowed_hosts_str = args.allowed_hosts or os.getenv("NEO4J_MCP_SERVER_ALLOWED_HOSTS", "localhost,127.0.0.1")
+    allowed_hosts = [host.strip() for host in allowed_hosts_str.split(",") if host.strip()] if allowed_hosts_str else []
+
     try:
         asyncio.run(server.main(
-            args.client_id, 
+            args.client_id,
             args.client_secret,
             args.transport or os.getenv("NEO4J_TRANSPORT", "stdio"),
             args.server_host or os.getenv("NEO4J_MCP_SERVER_HOST", "127.0.0.1"),
-            args.server_port or os.getenv("NEO4J_MCP_SERVER_PORT", 8000),
+            int(args.server_port or os.getenv("NEO4J_MCP_SERVER_PORT", 8000)),
             args.server_path or os.getenv("NEO4J_MCP_SERVER_PATH", "/mcp/"),
+            allow_origins,
+            allowed_hosts,
         ))
     except KeyboardInterrupt:
         logger.info("Server stopped by user")

servers/mcp-neo4j-cloud-aura-api/src/mcp_neo4j_aura_manager/server.py

@@ -3,6 +3,9 @@
 from fastmcp.server import FastMCP
 from mcp.types import ToolAnnotations
 from pydantic import Field
+from starlette.middleware import Middleware
+from starlette.middleware.cors import CORSMiddleware
+from starlette.middleware.trustedhost import TrustedHostMiddleware
 
 from .aura_manager import AuraManager
 from .utils import get_logger
@@ -13,7 +16,7 @@
 def create_mcp_server(aura_manager: AuraManager) -> FastMCP:
     """Create an MCP server instance for Aura management."""
 
-    mcp: FastMCP = FastMCP("mcp-neo4j-aura-manager", dependencies=["requests", "pydantic"], stateless_http=True)
+    mcp: FastMCP = FastMCP("mcp-neo4j-aura-manager", dependencies=["requests", "pydantic", "starlette"])
 
     @mcp.tool(annotations=ToolAnnotations(title="List Instances",
                                           readOnlyHint=True,
@@ -183,31 +186,57 @@ async def delete_instance(instance_id: str) -> dict:
 
 
 async def main(
-    client_id: str, 
+    client_id: str,
     client_secret: str,
     transport: Literal["stdio", "sse", "http"] = "stdio",
     host: str = "127.0.0.1",
     port: int = 8000,
     path: str = "/mcp/",
+    allow_origins: list[str] = [],
+    allowed_hosts: list[str] = [],
 ) -> None:
     """Start the MCP server."""
     logger.info("Starting MCP Neo4j Aura Manager Server")
 
     aura_manager = AuraManager(client_id, client_secret)
-    
+    custom_middleware = [
+        Middleware(
+            CORSMiddleware,
+            allow_origins=allow_origins,
+            allow_methods=["GET", "POST"],
+            allow_headers=["*"],
+        ),
+        Middleware(TrustedHostMiddleware,
+                   allowed_hosts=allowed_hosts)
+    ]
+
     # Create MCP server
     mcp = create_mcp_server(aura_manager)
 
     # Run the server with the specified transport
     match transport:
         case "http":
-            await mcp.run_http_async(host=host, port=port, path=path)
+            logger.info(
+                f"Running Neo4j Aura Manager MCP Server with HTTP transport on {host}:{port}..."
+            )
+            await mcp.run_http_async(
+                host=host, port=port, path=path, middleware=custom_middleware, stateless_http=True
+            )
         case "stdio":
+            logger.info("Running Neo4j Aura Manager MCP Server with stdio transport...")
             await mcp.run_stdio_async()
         case "sse":
-            await mcp.run_sse_async(host=host, port=port, path=path)
+            logger.info(
+                f"Running Neo4j Aura Manager MCP Server with SSE transport on {host}:{port}..."
+            )
+            await mcp.run_http_async(host=host, port=port, path=path, middleware=custom_middleware, transport="sse", stateless_http=True)
         case _:
-            raise ValueError(f"Unsupported transport: {transport}")
+            logger.error(
+                f"Invalid transport: {transport} | Must be either 'stdio', 'sse', or 'http'"
+            )
+            raise ValueError(
+                f"Invalid transport: {transport} | Must be either 'stdio', 'sse', or 'http'"
+            )
 
 
 if __name__ == "__main__":