Neo4j MCP Server

Instructions

Implementation Reference

• src/index.ts:157-164 (handler)

  The executeQuery method implements the core logic of the neo4j-query tool by running the Cypher query on the Neo4j database and returning the records.

  async executeQuery(query: string, parameters: Record<string, any> = {}) {
      const session = this.driver.session();
      try {
          const result = await session.run(query, parameters);
          return result.records;
      } finally {
          await session.close();
      }

• src/index.ts:97-115 (schema)

  The tool schema definition including name, description, and input schema for the neo4j-query tool.

  {
      name: "neo4j-query",
      description: "Execute a Cypher query against the Neo4j database",
      inputSchema: {
          type: "object",
          properties: {
              query: {
                  type: "string",
                  description: "The Cypher query to execute"
              },
              parameters: {
                  type: "object",
                  description: "Query parameters (optional)",
                  additionalProperties: true
              }
          },
          required: ["query"]
      }
  }

• src/index.ts:126-131 (registration)

  Switch case dispatching calls to the neo4j-query tool handler within the CallToolRequestSchema handler.

  case "neo4j-query":
      response = await this.executeQuery(
          args.query as string,
          args.parameters as Record<string, any>
      );
      break;

• src/index.ts:174-190 (helper)

  Helper function that formats the Neo4j query result records into a human-readable text output.

  function formatResults(records: neo4j.Record[]) {
      if (!records || records.length === 0) {
          return "No results found.";
      }
  
      const output: string[] = ["Results:"];
      
      records.forEach((record, index) => {
          output.push(`\nRecord ${index + 1}:`);
          record.keys.forEach(key => {
              const value = record.get(key);
              output.push(`${String(key)}: ${formatValue(value)}`);
          });
      });
  
      return output.join('\n');
  }

• src/index.ts:192-218 (helper)

  Helper function to format Neo4j-specific data types (nodes, relationships, paths, etc.) into strings.

  function formatValue(value: any): string {
      if (value === null || value === undefined) {
          return 'null';
      }
  
      if (neo4j.isNode(value)) {
          return `Node(id=${value.identity}, labels=[${value.labels.join(', ')}], properties=${JSON.stringify(value.properties)})`;
      }
  
      if (neo4j.isRelationship(value)) {
          return `Relationship(id=${value.identity}, type=${value.type}, properties=${JSON.stringify(value.properties)})`;
      }
  
      if (neo4j.isPath(value)) {
          return `Path(length=${value.segments.length}, nodes=${value.segments.length + 1})`;
      }
  
      if (Array.isArray(value)) {
          return `[${value.map(formatValue).join(', ')}]`;
      }
  
      if (typeof value === 'object') {
          return JSON.stringify(value);
      }
  
      return String(value);
  }