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

Prerequisites

• Node.js 20+

• Docker and Docker Compose

• npm or yarn

Installation

1. Clone the repository and install dependencies:

2. Create environment file:

3. Build the TypeScript code:

Running with Docker

Start all services (Elasticsearch + CRUD API)

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

Stop services

Running Locally (Development)

Option 1: Docker for Elasticsearch only

1. Start only Elasticsearch:

2. Run the CRUD API in development mode:

Option 2: All local (requires local Elasticsearch)

Ensure Elasticsearch is running locally on port 9200, then:

CRUD API Endpoints

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

Health Check

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):

For production:

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

Or for development with tsx:

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:

2. list_cities

List all Italian cities in the database.

Example:

3. get_city

Get a specific Italian city by ID.

Parameters:

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

Example:

4. search_cities

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

Parameters:

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

Example:

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:

6. delete_city

Delete an Italian city from the database.

Parameters:

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

Example:

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:

Project Structure

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

Watch mode for MCP server

Build TypeScript

License

MIT