# Neo4j MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes a
Neo4j graph database as tools an AI agent can call. It serves the MCP protocol over
HTTP, so it can be reached by any MCP client — including a Databricks Unity Catalog
MCP connection.

## Tools

| Tool | Purpose |
|------|---------|
| `read_neo4j`  | Run a read-only Cypher query (`MATCH` / `RETURN`). Write keywords are rejected. |
| `write_neo4j` | Run a write Cypher query (`CREATE` / `MERGE` / `SET` / `DELETE`). |
| `get_neo4j_schema` | Return the graph schema — node labels, relationship types, properties, and connection patterns. Call this first so queries use the right labels/relationships instead of guessing. |

## Requirements

- Node.js 20+
- A Neo4j database (e.g. [Neo4j Aura](https://neo4j.com/cloud/aura/))

## Setup

```bash
npm install
cp .env.example .env      # then fill in your Neo4j credentials + a secret token
npm run build
npm start                 # serves on http://localhost:3000
```

Endpoints:

- `GET  /health` — liveness check
- `POST /mcp`    — the MCP endpoint (requires `Authorization: Bearer <MCP_SECRET_TOKEN>`)

Optional: `npm run seed` loads sample data into Neo4j.

## Environment

See `.env.example`. Copy it to `.env` and fill in:

| Variable | Description |
|----------|-------------|
| `NEO4J_URI` | Bolt/Aura connection URI, e.g. `neo4j+s://<id>.databases.neo4j.io` |
| `NEO4J_USERNAME` | Neo4j username |
| `NEO4J_PASSWORD` | Neo4j password |
| `PORT` | HTTP port (default `3000`) |
| `MCP_SECRET_TOKEN` | Bearer token clients must present on `/mcp` |

> `.env` is git-ignored. Never commit real credentials.

## Exposing it to Databricks (or any remote client)

The server listens on localhost. To let a remote MCP client reach it during
development, expose the port with a tunnel:

```bash
ngrok http 3000
```

Then register the public URL as a UC HTTP/MCP connection in Databricks, using
`Authorization: Bearer <MCP_SECRET_TOKEN>`. For production, host the server on a
reachable machine instead of a tunnel.

## Project layout

```
neo4j-mcp-server/
├── src/
│   ├── index.ts   # the MCP server (tools + HTTP transport)
│   └── seed.ts    # optional sample-data seeder
├── package.json
├── tsconfig.json
├── .env.example
└── .gitignore
```