Kolkata Puja Tourist MCP Server

An open-source Model Context Protocol (MCP) server that provides structured Kolkata Durga Puja tourism information to AI assistants. The server exposes pandal, metro, route, restaurant, and restaurant-opening-hours tools so an AI chatbot can answer tourist queries using the project's curated datasets and external routing services.

Developed at JANTRAM LAB, under the guidance of Dr. Ritesh Sarkhel.

Overview

The Kolkata Puja Tourist MCP Server is designed as the tool/data layer behind an AI tourist assistant.

Tourist
   ↓
AI Chatbot / LLM
   ↓
MCP Client
   ↓
Kolkata Puja Tourist MCP Server
   ├── Pandal Dataset
   ├── Metro Dataset
   ├── Restaurant Dataset
   ├── OpenStreetMap
   └── OSRM Routing Service

The project focuses on making Kolkata Durga Puja information accessible to an AI assistant through well-defined MCP tools rather than implementing the chatbot itself.

Related MCP server: Korea Tourism API MCP Server

Problem

During Durga Puja, tourists may need to answer questions such as:

• Which pandals are in a particular area?

• Which pandals are close to another pandal?

• Which metro station is nearest to a pandal?

• What is the route between two or more pandals?

• Which restaurants are nearby?

• Is a restaurant listed as open at a particular date and time?

• How can a multi-stop Puja visit be planned?

The MCP server provides structured functions for these tasks so an MCP-compatible AI assistant can access the project's tourism data and services.

Features

• Search and retrieve Durga Puja pandal information.

• Find pandals within a specified radius.

• Find pandals near a named pandal using the exact coordinates stored in the dataset.

• Find the nearest Metro station to a location or named pandal.

• Calculate driving routes between pandals.

• Create a multi-stop driving route in the order supplied by the user.

• Search for restaurants.

• Find restaurants near a location or named pandal.

• Check restaurant opening hours for a specified date and time.

• Expose project datasets as MCP resources.

• Integrate with Claude Desktop through a local MCP server.

• Validate dataset structure, IDs, and coordinates at startup.

• Provide clearer OSRM/network error reporting.

• Include automated tests for core MCP functionality.

Technology Stack

• Python

• MCP Python SDK

• Claude Desktop for AI-client integration and testing

• OpenStreetMap (OSM) for open geographic, restaurant, and metro data

• OSRM for driving-route calculation

• JSON datasets for project data

• Pytest for automated testing

Project Structure

kolkata-puja-mcp/
│
├── src/
│   ├── server.py
│   └── client.py
│
├── data/
│   ├── pandals_2026.json
│   ├── metro_stations.json
│   └── restaurants.json
│
├── tests/
│   ├── test_server.py
│   └── test_named_location_tools.py
│
├── README.md
├── evaluation.md
├── requirements.txt
├── requirements-dev.txt
├── .gitignore
└── LICENSE

MCP Tools

The current server exposes 12 MCP tools.

MCP Resources

The server exposes 3 MCP resources:

Data Sources

Pandal Data

The 2026 pandal dataset currently contains records identified as P001 through P021.

The dataset source is recorded as:

PujoKolkata 2026

The project retains source/provenance information with the dataset and does not present the pandal records as a complete or universally official list of all Kolkata pandals.

Popularity-based ranking is not currently implemented because the current dataset does not contain a reliable popularity field.

Metro Data

Metro station data was collected from OpenStreetMap using Overpass-style geographic queries and cleaned for use by the MCP server.

The current cleaned dataset represents physical station records and merges obvious duplicate interchange entries where appropriate.

Metro/nearby distances calculated by the server are straight-line geographic distances from station coordinates. They are not walking distances.

Restaurant Data

Restaurant data was collected from OpenStreetMap and includes fields such as:

• Restaurant name

• Latitude/longitude

• Opening hours

• Address, when available

• Cuisine, when available

• Source

• OSM license/provenance information

• Check date, when present in the source data

OpenStreetMap data is licensed under the Open Database License (ODbL). See the attribution section below.

Restaurant opening-hours checks are based on recorded dataset values and are not live restaurant status or reservation availability.

Installation

1. Clone the repository

git clone <YOUR_GITHUB_REPOSITORY_URL>
cd kolkata-puja-mcp

2. Create a virtual environment

Windows PowerShell:

python -m venv .venv
.venv\\Scripts\\Activate.ps1

Windows Command Prompt:

python -m venv .venv
.venv\\Scripts\\activate

Linux/macOS:

python3 -m venv .venv
source .venv/bin/activate

3. Install runtime dependencies

pip install -r requirements.txt

4. Install development/test dependencies

pip install -r requirements-dev.txt

Running the MCP Server

The server can be launched using the MCP command-line interface:

mcp run src/server.py

The server uses stdio transport, so it normally waits for an MCP client rather than displaying a conventional web-server page.

Running the MCP Client

The included client can be started with:

python src/client.py

The client connects to the local MCP server and can list and call available tools and resources.

Claude Desktop Integration

The project has been tested with Claude Desktop using a local MCP configuration.

A typical configuration is:

{
  "mcpServers": {
    "kolkata-puja": {
      "command": "D:\\kolkata-puja-mcp\\.venv\\Scripts\\mcp.exe",
      "args": [
        "run",
        "D:\\kolkata-puja-mcp\\src\\server.py"
      ]
    }
  }
}

Change the paths to match the local installation.

After restarting Claude Desktop, the kolkata-puja MCP server should appear in the connected/local MCP tools area.

For controlled MCP evaluation, Web Search can be disabled so that responses are based on the connected project context rather than competing web-search results.

Natural-language usage

The intended user experience does not require a tourist to mention MCP or tool names. A tourist can ask ordinary questions such as:

What Durga Puja pandals are within 2 km of Deshapriya Park?

The AI client may decide whether to invoke an MCP tool or use available MCP resource context. Tool invocation is model/client-selected and is not guaranteed for every query.

Example Tourist Queries

Show me Durga Puja pandals in Kalighat.

Tell me about Deshapriya Park.

What pandals are within 2 km of Deshapriya Park?

Which metro station is nearest to Deshapriya Park?

Find restaurants near Deshapriya Park.

Is Prema Vilas open at 8 PM on September 22, 2026?

Give me a driving route from Deshapriya Park to Hindustan Park.

Plan a driving route through Deshapriya Park, Hindustan Park, and Ekdalia Evergreen Club.

Testing and Evaluation

Automated Tests

The final project includes automated tests covering:

• Pandal lookup

• Unknown pandal handling

• Pandal search

• Nearby pandal search

• Named-pandal nearby search

• Metro lookup

• Named-pandal Metro lookup

• Route handling

• Multi-stop route handling

• Restaurant search

• Nearby restaurant search

• Named-pandal restaurant search

• Restaurant opening-hours evaluation

• Unknown restaurant handling

• Dataset validation

• Duplicate-ID validation

• Coordinate validation

• Routing error handling

Final automated test result:

24 passed

Natural-language Evaluation

The MVP was also evaluated through Claude Desktop using natural-language tourist queries.

The evaluation covered:

• Pandal search and details

• Nearby pandals

• Nearest Metro

• Driving routes

• Multi-stop routing

• Restaurant search

• Nearby restaurants

• Timestamp-based restaurant opening-hours checks

• Combined multi-tool tourist queries

• Unknown records

• Grounding behavior

See evaluation.md for the detailed evaluation report.

Important Evaluation Observation

Two concepts should be distinguished:

1. Answer correctness

2. Explicit MCP tool invocation

An MCP-compatible LLM may sometimes answer correctly from available MCP resource context without explicitly calling a matching tool. The tools remain available and function correctly when invoked.

The final evaluation confirmed that the MCP tools themselves are functioning correctly, while model-side tool selection can vary by query and conversational context.

Data and Geographic Semantics

Nearby and Metro distance

Nearby-pandal, nearby-restaurant, and nearest-Metro calculations use straight-line geographic distance based on coordinates.

These values are not walking distances or road distances.

Routing

OSRM currently uses its driving profile.

Therefore:

• route distances are driving-route distances

• route durations are driving-time estimates

• walking routes are not implemented

• cycling routes are not implemented

• public-transit routing is not implemented

Named-location handling

When a user names a pandal, the named-location tools resolve that pandal against the project's dataset and use the stored coordinates rather than estimating coordinates from general knowledge.

Known Limitations

1. Pandal popularity

Popularity/ranking is not currently implemented. The server must not invent popularity scores or claims that are not present in the dataset.

2. Dataset scope

The current MVP uses curated project datasets. Coverage may not represent every Kolkata Durga Puja pandal, restaurant, or all Metro metadata.

3. Restaurant availability

Restaurant opening-hour checks use recorded opening_hours values. They do not provide live operational status or reservation availability.

4. Opening-hours parser

The current parser supports a practical subset of common OpenStreetMap opening_hours expressions. More complex schedules may return unknown.

5. Routing profile

Routing currently uses OSRM's driving profile only.

6. Route optimization

plan_puja_route follows the order supplied by the caller. It does not automatically optimize stop order.

7. Live information

The current MVP does not provide:

• Live crowd information

• Live restaurant status

• Live restaurant reservations

• Live Metro service status

• Real-time road-closure information

8. Automatic current location

The geographic tools accept coordinates. Automatic access to a tourist's live GPS location is not implemented inside the MCP server.

9. LLM tool selection

The LLM/client decides when to invoke an MCP tool. A matching tool being available does not guarantee explicit tool invocation for every natural-language query.

Future Improvements

Possible extensions include:

• Add a reliable, sourced popularity metric for pandals.

• Add more verified pandal records.

• Add richer pandal metadata such as themes and visiting information when reliable sources are available.

• Add Metro line information and interchange metadata.

• Add walking and public-transport routing.

• Improve multi-stop route optimization.

• Implement more complete OSM opening_hours parsing.

• Integrate live restaurant availability where an appropriate API is available.

• Add richer tourist itinerary planning.

• Add stronger application-level response-grounding safeguards.

• Add CI checks for Python syntax and dataset validity.

OpenStreetMap Attribution

This project uses data from OpenStreetMap.

OpenStreetMap data is available under the Open Database License (ODbL).

For more information:

https://www.openstreetmap.org/copyright

The project should retain appropriate attribution and comply with ODbL requirements when redistributing or using derived OSM data.

Project Status

Status: Functional MVP

The current implementation provides:

• MCP server architecture

• 12 MCP tools

• 3 MCP resources

• Pandal, Metro, and restaurant datasets

• Dataset validation

• OSRM driving-route integration

• Restaurant opening-hours evaluation

• Named-location geographic tools

• Claude Desktop integration

• Automated testing with 24 passing tests

• Evaluation documentation

The main explicitly unimplemented feature from the original project requirements is popularity-based pandal ranking, because a reliable popularity data source has not yet been added.