Content
# LiteAPI MCP Server
MCP server for LiteAPI using Next.js and mcp-handler (Streamable HTTP). Deploys to Vercel.
## Quick Start
```bash
npm install
npm run dev
```
MCP endpoint: `http://localhost:3000/api/mcp`
## ChatGPT Setup
Add to ChatGPT MCP Server URL:
```
https://mcp.liteapi.travel/api/mcp?apiKey=YOUR_LITEAPI_KEY
```
Or set `LITEAPI_API_KEY` in Vercel environment variables for single-tenant deployment.
---
## Features
- 🔄 **Dynamic Tool Generation**: Automatically generates MCP tools from OpenAPI specs
- 📚 **Multiple API Modules**: Supports Search, Booking, Vouchers, Analytics, Static, Loyalty, and Supply Customization APIs
- 🔐 **API Key Authentication**: Secure API key management via environment variables
- 🎯 **Type-Safe**: Uses Zod for schema validation and type safety
- 🚀 **Easy Integration**: Works with Claude Desktop and other MCP-compatible clients
## Prerequisites
- Node.js 18+
- npm or yarn
- LiteAPI API Key
## Installation
1. Clone the repository and install dependencies:
```bash
npm install
```
2. Build the TypeScript code:
```bash
npm run build
```
3. Set your LiteAPI API key as an environment variable:
```bash
export LITEAPI_API_KEY=your_api_key_here
```
## Usage
### Running the Server
The server runs on stdio (standard input/output) for MCP communication:
```bash
npm start
```
Or for development with auto-reload:
```bash
npm run dev
```
## Testing
### Quick Test
Test that the server works correctly:
```bash
export LITEAPI_API_KEY=your_api_key_here
npm test
```
This will connect to the server and list all available tools.
### Option 1: Using MCP Inspector (Recommended for Development)
MCP Inspector is a browser-based tool for testing and debugging MCP servers. It's perfect for inspecting tools, testing calls, and debugging without needing Claude Desktop.
1. **Install and run MCP Inspector:**
```bash
# Make sure your API key is set
export LITEAPI_API_KEY=your_api_key_here
# Run the inspector (it will automatically start your server)
npm run inspect
# Or directly:
npx @modelcontextprotocol/inspector node dist/index.js
```
2. **The inspector will:**
- Open a browser window at `http://localhost:6274`
- Start a proxy server on port 6277
- Display all available tools with their schemas
- Allow you to test tool calls interactively
- Show real-time notifications and responses
3. **In the Inspector UI, you can:**
- **Tools Tab**: See all available tools, their descriptions, and input schemas
- **Test Tools**: Click on any tool to test it with sample parameters
- **View Responses**: See formatted JSON responses from API calls
- **Debug**: Check for errors and validation issues
**Note:** Make sure Node.js 22.7.5+ is installed for MCP Inspector (check with `node --version`).
### Option 2: Testing with a Simple Client Script
Create a test script to verify the server works:
```bash
# Create test-client.js
cat > test-client.js << 'EOF'
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
async function test() {
const transport = new StdioClientTransport({
command: 'node',
args: ['dist/index.js'],
env: { LITEAPI_API_KEY: process.env.LITEAPI_API_KEY }
});
const client = new Client({
name: 'test-client',
version: '1.0.0'
}, {
capabilities: {}
});
await client.connect(transport);
// List all available tools
const tools = await client.listTools();
console.log(`Found ${tools.tools.length} tools:`);
tools.tools.forEach(tool => {
console.log(` - ${tool.name}: ${tool.description}`);
});
await client.close();
}
test().catch(console.error);
EOF
# Run the test
export LITEAPI_API_KEY=your_api_key_here
node test-client.js
```
### Option 3: Connecting to Claude Desktop
1. **Get the absolute path to your project:**
```bash
# macOS/Linux
pwd
# Output: /Users/nicholas/Documents/nuitee/liteapi/mcp-server
# Windows (PowerShell)
(Get-Location).Path
```
2. **Open Claude Desktop configuration file:**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
If the file doesn't exist, create it with an empty JSON object: `{}`
3. **Add the server configuration:**
```json
{
"mcpServers": {
"liteapi": {
"command": "node",
"args": ["/absolute/path/to/mcp-server/run-mcp-server.mjs"],
"env": {
"LITEAPI_API_KEY": "your_api_key_here"
}
}
}
}
```
**Important**:
- Use `run-mcp-server.mjs` instead of `dist/index.js` to ensure ES modules work correctly
- Replace `/absolute/path/to/mcp-server` with the actual absolute path to this project
- Replace `your_api_key_here` with your actual LiteAPI API key
- On Windows, use forward slashes `/` or escaped backslashes `\\` in the path
**Example for macOS:**
```json
{
"mcpServers": {
"liteapi": {
"command": "node",
"args": ["/Users/nicholas/Documents/nuitee/liteapi/mcp-server/run-mcp-server.mjs"],
"env": {
"LITEAPI_API_KEY": "sand_c0155ab8-c683-4f26-8f94-b5e92c5797b9"
}
}
}
}
```
**Note:** The `.mjs` wrapper script ensures Node.js correctly recognizes ES modules when running from Claude Desktop. If you prefer to use `dist/index.js` directly, make sure Claude Desktop runs it from the project root directory.
4. **Restart Claude Desktop** completely (quit and reopen)
5. **Verify connection:**
- Open Claude Desktop
- Start a new conversation
- Look for MCP tools indicator (usually shows available tools)
- Try asking: "What LiteAPI tools are available?" or "Search for hotels in Paris"
### Troubleshooting Connection Issues
**If Claude Desktop doesn't recognize the server:**
1. **Check the path is correct:**
```bash
# Test that the file exists and is executable
ls -la /absolute/path/to/mcp-server/dist/index.js
node /absolute/path/to/mcp-server/dist/index.js
```
2. **Check Claude Desktop logs:**
- macOS: `~/Library/Logs/Claude/claude_desktop.log`
- Windows: `%APPDATA%\Claude\logs\`
- Look for errors related to MCP server startup
3. **Verify JSON syntax:**
```bash
# Validate JSON syntax
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool
```
4. **Test server manually:**
```bash
export LITEAPI_API_KEY=your_api_key_here
node dist/index.js
# Should output: "Loaded X endpoints from Y OpenAPI specs"
# Should output: "LiteAPI MCP Server running on stdio"
```
5. **Check Node.js version:**
```bash
node --version
# Should be 18.0.0 or higher
```
### Available Tools
The server automatically generates tools from all OpenAPI specs in the `openapi-schemas/` directory. Each endpoint becomes a callable MCP tool with:
- **Operation ID** as the tool name
- **Description** from the OpenAPI spec
- **Parameters** automatically extracted and validated
Example tools include:
- `post_hotels_rates` - Search for hotel rates
- `get_prebooks_{prebookId}` - Retrieve prebook details
- `post_bookings` - Create a booking
- And many more...
## Project Structure
```
.
├── src/
│ ├── index.ts # Entry point
│ ├── server.ts # Main MCP server implementation
│ └── utils/
│ ├── openapi-parser.ts # OpenAPI spec parsing
│ ├── schema-converter.ts # OpenAPI to Zod conversion
│ └── api-client.ts # HTTP client for API calls
├── openapi-schemas/ # OpenAPI specification files
├── dist/ # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md
```
## Development
### Building
```bash
npm run build
```
### Watching for Changes
```bash
npm run watch
```
### Adding New OpenAPI Specs
1. Add your OpenAPI spec JSON file to `openapi-schemas/`
2. Update the `specFiles` array in `src/utils/openapi-parser.ts` if needed
3. Rebuild and restart the server
## Environment Variables
- `LITEAPI_API_KEY` (required): Your LiteAPI API key for authentication
## API Modules
The server supports the following LiteAPI modules:
- **Search** (`search.json`) - Hotel search and rate retrieval
- **Booking** (`booking.json`) - Booking management and prebook operations
- **Vouchers** (`voucher.json`) - Voucher creation and management
- **Analytics** (`analytics.json`) - Analytics and reporting
- **Static** (`static.json`) - Static data endpoints
- **Loyalty** (`loyalty.json`) - Loyalty program operations
- **Supply Customization** (`supplyCustomization.json`) - Supply customization
## Error Handling
The server includes comprehensive error handling:
- Missing API keys are caught at startup
- Invalid tool calls return descriptive error messages
- API request failures are properly formatted and returned
## License
MIT
## Support
For issues related to:
- **MCP Server**: Open an issue in this repository
- **LiteAPI**: Contact LiteAPI support
