Peru Top 10k MCP

A Neo4j graph database project ingesting the Top 10,000 Peruvian companies dataset, exposed via a Neo4j MCP server for natural language querying.

Prerequisites

• Docker and Docker Compose
• Node.js (v18+) and npm
• A .env file based on .env.example

1. Start the services

Bring up Neo4j and the Neo4j MCP server:

docker compose up -d

This starts two containers:

Container	Purpose	Ports
neo4j	Neo4j 5.12 database	7474 (browser), 7687 (bolt)
neo4j-mcp	Neo4j MCP HTTP server	8000

The Neo4j browser UI is available at http://localhost:7474 (credentials: neo4j / password123).

To stop the services:

docker compose down

2. Run the ingest process

The ingest script reads the CSV dataset and populates the Neo4j graph.

Install dependencies first (only needed once):

npm install

Then copy the environment file and run the ingest:

cp .env.example .env
npm run ingest

The script will create all nodes and relationships as defined in DESIGN.md. It is idempotent — running it multiple times will not create duplicate data.

Make sure the Neo4j container is running before executing the ingest.

3. Inspect the MCP server

Launch the MCP Inspector to explore and test the Neo4j MCP server:

npx @modelcontextprotocol/inspector

Once the inspector opens in your browser:

1. Set the transport type to Streamable HTTP.
2. Enter the URL: http://localhost:8000/mcp
3. Click Connect.

You can now browse available tools and send Cypher queries to the Neo4j database through the MCP protocol.

Make sure both containers are running (docker compose up -d) before connecting the inspector.