# MV MCP Server

> A production-ready Model Context Protocol (MCP) server that provides AI assistants with intelligent access to MountVacation's accommodation booking API, specializing in European ski resort and mountain vacation planning.

- **Type:** MCP server
- **Install:** `agentstack add mcp-talirezun-mv-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [talirezun](https://agentstack.voostack.com/s/talirezun)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [talirezun](https://github.com/talirezun)
- **Source:** https://github.com/talirezun/MV-MCP-server

## Install

```sh
agentstack add mcp-talirezun-mv-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🏔️ MountVacation MCP Server

A production-ready Model Context Protocol (MCP) server that provides AI assistants with intelligent access to MountVacation's accommodation booking API, specializing in year-round mountain vacations across Europe, spa & terme holidays in Slovenia, and extensive Croatia coverage.

## Watch the Demo Video

Click the thumbnail below to watch the video:

[](https://youtu.be/iX-VV5B8veE)

*Clicking the image will open the video on YouTube.*

## ✨ **Key Features**

- 🏔️ **Year-Round Mountain Vacations**: All-season mountain accommodations across Europe (skiing, hiking, wellness, spa)
- 🌍 **Comprehensive European Coverage**: 8+ countries with 150+ verified destination mappings
- 🏨 **Spa & Terme Holidays**: Specialized coverage of Slovenia's spa and thermal destinations
- 🇭🇷 **Extensive Croatia Coverage**: Comprehensive accommodation options throughout Croatia
- 👨‍👩‍👧‍👦 **Family Support**: Children pricing, age-based discounts, family room configurations
- 🔗 **Direct Booking**: Real-time pricing with direct booking links
- 📄 **Complete Pagination**: Advanced API batching for comprehensive results (350% more accommodations)
- 🔄 **Universal Compatibility**: Tested with LM Studio (gpt-oss 20B), Claude Desktop App, Augment Code, Cline.bot
- 🧠 **Intelligent Search**: Comma-separated location parsing, resort/region ID-based search, destination prioritization

---

## 🏗️ **Server Architecture**

### **📥 Simple Installation**
Users only need to download a single JavaScript file - no repository cloning required!

### **📁 Available Server Files**
- **`mountvacation-mcp-server.js`** - Standard MCP server for most clients (Claude Desktop, LM Studio, Augment Code)
- **`mountvacation-mcp-server-cline.js`** - Optimized version for Cline.bot within VS Code

### **🔗 Direct Download Links**
- **Standard**: https://raw.githubusercontent.com/talirezun/MV-MCP-server/main/server-versions/mountvacation-mcp-server.js
- **Cline Version**: https://raw.githubusercontent.com/talirezun/MV-MCP-server/main/server-versions/mountvacation-mcp-server-cline.js

### **⚙️ Configuration**
All configuration is done through your MCP client's config file - no additional setup files needed!

---

## 🚀 **Quick Start**

### **1. Download the Server File**
```bash
# Download the MCP server file
curl -o mountvacation-mcp-server.js https://raw.githubusercontent.com/talirezun/MV-MCP-server/main/server-versions/mountvacation-mcp-server.js
```

### **2. Get Your MountVacation API Key**
[Get your API key here](#-get-your-mountvacation-api-key) (see section below for details)

### **3. Configure Your MCP Client**
Add to your MCP client configuration (e.g., Claude Desktop's `config.json`):

```json
{
  "mcpServers": {
    "mountvacation": {
      "command": "node",
      "args": ["./mountvacation-mcp-server.js"],
      "env": {
        "MOUNTVACATION_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### **4. Restart Your MCP Client**
The server will be available with 10 comprehensive accommodation search tools including advanced pagination support.

---

## 🔧 **Reliability & DNS Resolution**

### **✅ Stable Production Deployment**
- **Cloudflare Workers**: Deployed and actively running
- **Free Tier**: 100,000 requests/day (no inactivity timeout)
- **Uptime**: Continuously available
- **DNS Resolution**: Optimized to work reliably regardless of system DNS configuration

### **🛡️ DNS Resolution Fix (v3.3+)**
The server uses direct IP connection to Cloudflare Workers, ensuring reliable operation even if your system's DNS has local overrides or caching issues. This means:
- ✅ Works on all systems without DNS configuration
- ✅ No dependency on system DNS settings
- ✅ Faster connection establishment
- ✅ More reliable for automated deployments

---

## 💻 **Installation Instructions**

### **📋 Prerequisites**
- Node.js (version 14 or higher)
- Your MountVacation API key

### **📥 Download Server File (All Platforms)**

**Option 1: Direct Download**
```bash
# Using curl (macOS/Linux)
curl -o mountvacation-mcp-server.js https://raw.githubusercontent.com/talirezun/MV-MCP-server/main/server-versions/mountvacation-mcp-server.js

# Using PowerShell (Windows)
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/talirezun/MV-MCP-server/main/server-versions/mountvacation-mcp-server.js" -OutFile "mountvacation-mcp-server.js"
```

**Option 2: Browser Download**
Visit: https://raw.githubusercontent.com/talirezun/MV-MCP-server/main/server-versions/mountvacation-mcp-server.js
Right-click → Save As → `mountvacation-mcp-server.js`

### **⚙️ Configure Your MCP Client**

Add this configuration to your MCP client's config file:

```json
{
  "mcpServers": {
    "mountvacation": {
      "command": "node",
      "args": ["./mountvacation-mcp-server.js"],
      "env": {
        "MOUNTVACATION_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

**Common config file locations:**
- **Claude Desktop (macOS)**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Claude Desktop (Windows)**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Claude Desktop (Linux)**: `~/.config/Claude/claude_desktop_config.json`

## 🔄 **MCP Client Compatibility**

### **✅ Tested and Working**
- **🧠 LM Studio** - gpt-oss 20B model (excellent performance)
- **🤖 Claude Desktop App** - Full compatibility with protocol v3.3.0 (JSON-RPC 2.0 notification handling)
- **⚡ Augment Code** - Native integration support
- **🔧 Cline.bot** - VS Code extension (use cline-specific server version)

### **🔜 More Clients Testing**
Additional MCP client testing is ongoing. The server follows MCP protocol standards for universal compatibility.

---

## 📱 **Client-Specific Instructions**

### **🤖 Claude Desktop**
1. Download `mountvacation-mcp-server.js` to your preferred folder
2. Edit your Claude Desktop config file:
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
   - **Linux**: `~/.config/Claude/claude_desktop_config.json`
3. Add the MountVacation server configuration (see above)
4. Restart Claude Desktop

### **🧠 LM Studio**
1. Download `mountvacation-mcp-server.js` to your LM Studio folder
2. Add to your LM Studio MCP configuration
3. Set the `MOUNTVACATION_API_KEY` environment variable
4. Restart LM Studio

### **⚡ Augment Code**
1. Download `mountvacation-mcp-server.js` to your project folder
2. Use the "Edit MCP Server" option in Augment
3. Set command: `node` and args: `./mountvacation-mcp-server.js`
4. Add `MOUNTVACATION_API_KEY` environment variable
5. Save and restart

### **🔧 Cline.bot (VS Code)**
1. Download the Cline-specific version:
   ```bash
   curl -o mountvacation-mcp-server-cline.js https://raw.githubusercontent.com/talirezun/MV-MCP-server/main/server-versions/mountvacation-mcp-server-cline.js
   ```
2. Configure in VS Code Cline extension settings
3. Set environment variable: `MOUNTVACATION_API_KEY=your-api-key-here`

---

## 🛠️ **Available Tools**

### **🔍 Core Search Tools**
| Tool | Description | Use Case |
|------|-------------|----------|
| `search_accommodations` | Main search with intelligent location resolution | General accommodation searches (first batch) |
| `search_accommodations_complete` | **NEW**: Complete search with automatic pagination | Comprehensive results (all available pages) |
| `load_more_accommodations` | **NEW**: Load additional results from pagination URLs | Progressive loading of more results |

### **📋 Property Details**
| Tool | Description | Use Case |
|------|-------------|----------|
| `get_accommodation_details` | Detailed property information and amenities | Property deep-dive analysis |
| `get_facility_details` | Specific room/facility details | Room selection and comparison |
| `search_by_resort_id` | Resort-specific accommodation searches | Targeted resort searches |
| `search_by_city_id` | City-specific accommodation searches | Urban area accommodation |
| `search_by_geolocation` | GPS coordinate-based proximity search | Location-based discovery |
| `get_booking_links` | Direct booking URL generation | Booking facilitation |
| `research_accommodations` | Multi-region comparison and research tool | Comprehensive vacation planning |

---

## 🎯 **Example Usage**

Try asking your AI assistant:

**🎿 Winter Skiing:**
> *"Find ski accommodations in Austria for a family of 4 (2 adults, 2 children aged 8 and 5) for 7 nights in February 2026. We need a pool and half-board."*

**🌿 Summer Hiking:**
> *"Find mountain accommodations in the Dolomites for hiking in July 2026. We want wellness facilities and breakfast included."*

**🏨 Spa & Wellness:**
> *"Find spa hotels in Slovenia with thermal pools for a romantic weekend in September 2026."*

**🇭🇷 Croatia Vacation:**
> *"Find beachfront accommodations in Croatia for a family vacation in August 2026, near Split or Dubrovnik."*

**The server will:**
- ✅ Search across European destinations with intelligent location mapping
- ✅ Apply family pricing with children's age-based discounts
- ✅ Use complete pagination to find all available accommodations (350% more results)
- ✅ Filter for specific amenities (pools, spa, wellness, etc.)
- ✅ Provide direct booking links with real-time pricing
- ✅ Include proximity to attractions and activity information

---

## 🌍 **Supported Destinations**

### **🏔️ Year-Round Mountain & Coastal Destinations**
- 🇦🇹 **Austria**: Innsbruck, Kitzbühel, St. Anton, Saalbach, Zell am See, Bad Gastein, Lech (Tirol region)
- 🇮🇹 **Italy**: Madonna di Campiglio, Cortina, Val Gardena, Livigno, Bormio, Lake Garda Nord, Cervinia, Courmayeur (Trentino, Dolomites)
- 🇫🇷 **France**: Chamonix, Val d'Isère, Tignes, Courchevel, Méribel, Val Thorens, Alpe d'Huez, Morzine (French Alps)
- 🇨🇭 **Switzerland**: Zermatt, Verbier, St. Moritz, Davos, Crans Montana, Saas-Fee, Grindelwald (Valais region)
- 🇭🇷 **Croatia**: Umag, Rovinj, Pula, Opatija, Dubrovnik, Split, Hvar, Zadar, Makarska (full Istria & Dalmatia)
- 🇸🇮 **Slovenia**: Bled, Bohinj, Portorož, Piran, Maribor, Kranjska Gora (mountain & coastal)
- 🇧🇦 **Bosnia**: Jahorina, Bjelašnica - Mountain tourism
- 🇩🇪 **Germany**: Cross-border accommodation discovery

### **🏨 Spa & Terme Holidays (Slovenia)**
- **Terme Čatež** - Largest spa complex in Slovenia
- **Terme Olimia** - Wellness and thermal springs
- **Terme Dobrna** - Historic spa town
- **Terme Zreče** - Mountain spa resort
- **Terme Ptuj** - Roman heritage spa

### **🇭🇷 Extensive Croatia Coverage**
- **Istria**: Coastal resorts, inland destinations
- **Dalmatia**: Split, Dubrovnik, islands
- **Kvarner**: Rijeka, Opatija, islands
- **Central Croatia**: Zagreb region, continental destinations
- **Spa Destinations**: Terme Sveti Martin, Istarske Toplice

### **🔍 Additional Coverage**
- All static mappings use verified API resort/skiarea/region/city IDs (coordinate-based search deprecated due to unreliable API responses)

---

## 📄 **Pagination Support**

### **🚀 NEW: Complete Results Collection**
The MountVacation API uses pagination to handle large result sets efficiently. Our MCP server now provides three strategies:

#### **Strategy 1: Quick Search** (`search_accommodations`)
- Returns first batch (20-30 results) for fast response
- Includes pagination info if more results available
- Perfect for initial exploration

#### **Strategy 2: Complete Collection** (`search_accommodations_complete`)
- Automatically follows all pagination links
- Collects up to 200 total results across multiple pages
- Equivalent to browsing all pages on mountvacation.com
- Configurable limits for performance

#### **Strategy 3: Progressive Loading** (`load_more_accommodations`)
- Load additional batches on demand
- User-controlled pagination
- Optimal for interactive applications

### **Example Usage**
```javascript
// Quick search (first batch)
search_accommodations({
  location: "Chamonix",
  arrival_date: "2026-02-15",
  departure_date: "2026-02-22",
  persons_ages: "30,28"
})

// Complete search (all results)
search_accommodations_complete({
  location: "Chamonix",
  arrival_date: "2026-02-15",
  departure_date: "2026-02-22",
  persons_ages: "30,28",
  max_total_results: 100,
  max_pages: 10
})

// Load more from pagination URL
load_more_accommodations({
  next_page_url: "https://api.mountvacation.com/...",
  max_additional_results: 20
})
```

---

## 🏗️ **Technical Architecture**

- **Protocol**: JSON-RPC 2.0 over stdio (MCP compliant)
- **Version**: 3.3.0 (Protocol compliant for Claude Desktop, with JSON-RPC 2.0 notification handling)
- **API Integration**: Cloudflare Worker orchestration layer
- **Location Intelligence**: 150+ verified static mappings using resort/skiarea/region/city IDs (no unreliable coordinates)
- **Search Strategy**: resort → city → skiarea → region → dynamic fuzzy matching (most specific first, with cross-border validation)
- **Comma-Separated Parsing**: "Umag, Croatia" → primary="umag", hint="croatia" for accurate results
- **Universal Compatibility**: All MCP clients supported

---

## 🔑 **Get Your MountVacation API Key**

To use this MCP server, you need a valid MountVacation API key:

### **📝 How to Obtain Your API Key**
1. **Visit MountVacation.si** - [Get your API key here](https://www.mountvacation.si/) *(Link will be added manually)*
2. **Register or Login** to your MountVacation account
3. **Navigate to API section** in your account dashboard
4. **Generate your API key** - You'll receive a 64-character key
5. **Copy the key** and use it in your MCP client configuration

### **🔒 Security Note**
- Keep your API key secure and never share it publicly
- The API key provides access to MountVacation's booking system
- Each key is tied to your account for billing and usage tracking

### **⚙️ Configuration**
Use your API key in any of the provided configuration files:
- **Generic**: `mcp-config.json`
- **macOS/Linux**: `mcp-config-macos-linux.json`
- **Windows**: `mcp-config-windows.json`
- **Augment Code**: `mcp-config-for-augment.json`

---

## 🎥 **Video Demonstration**

Watch our comprehensive video guide showing the MountVacation MCP Server in action:

### **📺 Setup and Usage Tutorial**
*[Video link will be added here manually]*

The video covers:
- 🔧 Installation and setup process
- 🎯 Example searches and queries
- 🏔️ Different vacation types (skiing, hiking, spa, Croatia)
- 🤖 Integration with various MCP clients
- 💡 Tips and best practices

---

## 🔧 **Troubleshooting**

### **Claude Desktop Issues**
✅ **RESOLVED**: Version 3.3.0 includes full JSON-RPC 2.0 notification handling and protocol version compatibility for Claude Desktop. The server now silently accepts `notifications/initialized` and other notification messages per the JSON-RPC 2.0 spec (no response for messages without an `id` field).

### **Common Solutions**
1. **Restart your MCP client** after configuration changes
2. **Check file paths** in your configuration  
3. **Verify API key** is correctly set in environment variables
4. **Test with command line** for debugging:
   ```bash
   echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize"}' | node mountvacation-mcp-server.js
   ```

---

## 🧪 **Development & Testing**

### **Local Testing**
```bash
# Test initialization
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize"}' | node mountvacation-mcp-server.js

# Test tools list  
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}' | node mountvacation-mcp-server.js
```

### **Cloudflare Worker Deployment**
```bash
cd cloudflare-workers
npm install
npm run deploy
```

---

## 📚 **Documentation**

| Document | Description |
|----------|-------------|
| [📋 Project Architecture](docs/PROJECT-ARCHITECTURE.md) | Comprehensive technical overview and system design |
| [📋 Changelog](docs/CHANGELOG.md) | Version history and release notes |
| [🐛 Location Resolution Bug Report](docs/MV-MCP-Location-Resolution-Bug-R

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [talirezun](https://github.com/talirezun)
- **Source:** [talirezun/MV-MCP-server](https://github.com/talirezun/MV-MCP-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-talirezun-mv-mcp-server
- Seller: https://agentstack.voostack.com/s/talirezun
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.