Italian Cities MCP Server

A Model Context Protocol (MCP) server for managing Italian cities with CRUD operations backed by Elasticsearch.

Architecture

The project consists of three main components:

1. Elasticsearch Database: Stores Italian cities data with a simple schema (city name only)
2. CRUD API Server: Express.js REST API for managing cities
3. MCP Server: MCP interface that communicates with the CRUD API to provide tools for AI assistants

┌─────────────────┐
│   MCP Server    │
│  (stdio mode)   │
└────────┬────────┘
         │ HTTP
         ▼
┌─────────────────┐
│   CRUD API      │
│  (Express.js)   │
└────────┬────────┘
         │ REST
         ▼
┌─────────────────┐
│ Elasticsearch   │
│   (Database)    │
└─────────────────┘

Prerequisites

• Node.js 20+
• Docker and Docker Compose
• npm or yarn

Installation

1. Clone the repository and install dependencies:

npm install

2. Create environment file:

cp .env.example .env

3. Build the TypeScript code:

npm run build

Running with Docker

Start all services (Elasticsearch + CRUD API)

npm run docker:up

This will:

• Start Elasticsearch on port 9200
• Start the CRUD API on port 3000
• Create the index and initialize the database with 30 Italian cities

Check logs

npm run docker:logs

Stop services

npm run docker:down

Running Locally (Development)

Option 1: Docker for Elasticsearch only

1. Start only Elasticsearch:

docker-compose up -d elasticsearch

2. Run the CRUD API in development mode:

npm run dev:api

Option 2: All local (requires local Elasticsearch)

Ensure Elasticsearch is running locally on port 9200, then:

npm run dev:api

CRUD API Endpoints

The API server runs on http://localhost:3000 by default.

Health Check

GET /health

Cities Endpoints

• Create a city

  POST /api/cities
  Content-Type: application/json
  
  {"nome": "Venezia"}
  

• Get all cities

  GET /api/cities
  

• Get city by ID

  GET /api/cities/:id
  

• Search cities by name

  GET /api/cities/search/:name
  

• Update a city

  PUT /api/cities/:id
  Content-Type: application/json
  
  {"nome": "Venezia Mestre"}
  

• Delete a city

  DELETE /api/cities/:id
  

MCP Server

Running the MCP Server

For development (with auto-reload):

npm run dev:mcp

For production:

npm run start:mcp

Configuring in Claude Desktop

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "varolio-cities": {
      "command": "node",
      "args": [
        "/absolute/path/to/varolio/dist/mcp-server/index.js"
      ]
    }
  }
}

Or for development with tsx:

{
  "mcpServers": {
    "varolio-cities": {
      "command": "npx",
      "args": [
        "tsx",
        "/absolute/path/to/varolio/src/mcp-server/index.ts"
      ]
    }
  }
}

Important: Ensure the CRUD API server is running before using the MCP server.

MCP Tools

The MCP server provides the following tools:

1. create_city

Create a new Italian city in the database.

Parameters:

• nome (string, required): Name of the Italian city

Example:

Create a new city called "Siena"

2. list_cities

List all Italian cities in the database.

Example:

Show me all cities in the database

3. get_city

Get a specific Italian city by ID.

Parameters:

• id (string, required): ID of the city

Example:

Get the city with ID "abc123"

4. search_cities

Search for Italian cities by name (supports fuzzy matching).

Parameters:

• name (string, required): Name or partial name to search

Example:

Search for cities named "Milan"

5. update_city

Update an existing Italian city name.

Parameters:

• id (string, required): ID of the city to update
• nome (string, required): New name for the city

Example:

Update city with ID "abc123" to "Milano"

6. delete_city

Delete an Italian city from the database.

Parameters:

• id (string, required): ID of the city to delete

Example:

Delete the city with ID "abc123"

Database Initialization

The database is automatically initialized with 30 major Italian cities when the CRUD API starts for the first time. Cities include: Roma, Milano, Napoli, Torino, Palermo, Genova, Bologna, Firenze, and more.

To manually reinitialize the database:

npm run init:db

Project Structure

varolio/
├── src/
│   ├── types/              # TypeScript type definitions
│   ├── elasticsearch/      # Elasticsearch client and utilities
│   ├── crud-api/           # Express.js REST API
│   └── mcp-server/         # MCP server implementation
├── data/
│   └── init-cities.json    # Initial cities data
├── docker-compose.yml      # Docker orchestration
├── Dockerfile              # Node.js backend container
├── package.json            # Dependencies and scripts
└── tsconfig.json           # TypeScript configuration

Environment Variables

• ELASTICSEARCH_HOST: Elasticsearch host URL (default: http://localhost:9200)
• ELASTICSEARCH_INDEX: Index name for cities (default: citta_italiane)
• API_PORT: CRUD API port (default: 3000)
• API_HOST: CRUD API host (default: localhost)
• NODE_ENV: Node environment (default: development)

Development

Watch mode for API

npm run dev:api

Watch mode for MCP server

npm run dev:mcp

Build TypeScript

npm run build

License

MIT