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:
- Elasticsearch Database: Stores Italian cities data with a simple schema (city name only)
- CRUD API Server: Express.js REST API for managing cities
- 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
- Clone the repository and install dependencies:
npm install
- Create environment file:
cp .env.example .env
- 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
- Start only Elasticsearch:
docker-compose up -d elasticsearch
- 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 updatenome(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