# 🔍⁉️ Neo4j MCP Server (TypeScript)

## 🌟 Overview

A Model Context Protocol (MCP) server implementation in TypeScript that provides database interaction and allows graph exploration capabilities through Neo4j. This server enables running Cypher graph queries, analyzing complex domain data, and automatically generating business insights that can be enhanced with Claude's analysis.

This is a TypeScript port of the original Python [mcp-neo4j-cypher](https://github.com/neo4j-contrib/mcp-neo4j) server.

## 🧩 Components

### 🛠️ Tools

The server offers these core tools:

#### 📊 Query Tools
- `read_neo4j_cypher`
   - Execute Cypher read queries to read data from the database
   - Input: 
     - `query` (string): The Cypher query to execute
     - `params` (object, optional): Parameters to pass to the Cypher query
   - Returns: Query results as JSON serialized array of objects

- `write_neo4j_cypher`
   - Execute updating Cypher queries
   - Input:
     - `query` (string): The Cypher update query
     - `params` (object, optional): Parameters to pass to the Cypher query
   - Returns: A JSON serialized result summary counter with update statistics

#### 🕸️ Schema Tools
- `get_neo4j_schema`
   - Get a list of all node types in the graph database, their attributes with name, type and relationships to other node types
   - No input required
   - Returns: JSON serialized list of node labels with two dictionaries: one for attributes and one for relationships

### 🏷️ Namespacing

The server supports namespacing to allow multiple Neo4j MCP servers to be used simultaneously. When a namespace is provided, all tool names are prefixed with the namespace followed by a hyphen (e.g., `mydb-read_neo4j_cypher`).

## 📦 Installation

1. Clone this repository or copy the source files to your project
2. Install dependencies:
   ```bash
   cd neo4j-mcp-typesccript
   yarn install
   ```
3. Build the TypeScript code:
   ```bash
   yarn build
   ```

## 🧪 Testing the Connection

Before running the server, you can test your Neo4j connection:

```bash
yarn test:connection
```

This will verify that the server can connect to your Neo4j instance.

## 🚀 Usage

### 🖥️ Command Line

You can run the server directly from the command line:

```bash
# Using stdio transport (default)
node dist/index.js --db-url bolt://localhost:7687 --username neo4j --password password

# Using HTTP transport
node dist/index.js --transport http --server-host 0.0.0.0 --server-port 8000

# Using SSE transport
node dist/index.js --transport sse --server-host 0.0.0.0 --server-port 8000
```

### 🔧 Environment Variables

You can also configure the server using environment variables:

```bash
# Neo4j Connection
export NEO4J_URI=bolt://localhost:7687
export NEO4J_USERNAME=neo4j
export NEO4J_PASSWORD=password
export NEO4J_DATABASE=neo4j

# MCP Server Configuration
export NEO4J_TRANSPORT=stdio
export NEO4J_NAMESPACE=mydb
export NEO4J_MCP_SERVER_HOST=127.0.0.1
export NEO4J_MCP_SERVER_PORT=8000
export NEO4J_MCP_SERVER_PATH=/mcp/

# Then run
node dist/index.js
```

### 💻 Claude Desktop Integration

Add the server to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "neo4j-typescript": {
      "command": "node",
      "args": ["/path/to/neo4j-mcp-typescript/dist/index.js"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your-password",
        "NEO4J_DATABASE": "neo4j"
      }
    }
  }
}
```

### 🐳 Docker Support

You can also run this in a Docker container. Create a Dockerfile:

```dockerfile
FROM node:18-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./
RUN npm install

# Copy source files
COPY . .

# Build TypeScript
RUN npm run build

# Set environment variables
ENV NEO4J_URI="bolt://host.docker.internal:7687"
ENV NEO4J_USERNAME="neo4j"
ENV NEO4J_PASSWORD="password"
ENV NEO4J_DATABASE="neo4j"
ENV NEO4J_TRANSPORT="http"
ENV NEO4J_MCP_SERVER_HOST="0.0.0.0"
ENV NEO4J_MCP_SERVER_PORT="8000"
ENV NEO4J_MCP_SERVER_PATH="/api/mcp/"

EXPOSE 8000

CMD ["node", "dist/index.js"]
```

## 🚀 Transport Modes

The server supports different transport protocols:

- **STDIO** (default for local development): Standard input/output for Claude Desktop and local tools
- **HTTP**: RESTful HTTP for web deployments and microservices  
- **SSE**: Server-Sent Events for web-based deployments

## 🔧 Development

1. Clone the repository
2. Install dependencies: `yarn install`
3. Run in development mode: `yarn dev`
4. Build for production: `yarn build`
5. Run tests: `yarn test` (if tests are added)

## 📄 License

This MCP server is licensed under the MIT License.