Content
# Mess MCP Server
An MCP (Model Context Protocol) server for the IIIT Mess Management System. This allows AI assistants like Claude to interact with the mess portal through natural language.
## Features
- 🍽️ **View Menus** - Get menus for any date at all messes
- 📝 **Manage Registrations** - Register, cancel, or uncancel meals
- 💰 **Check Bills** - View your monthly mess bill with projections
- ⭐ **Submit Feedback** - Rate and review meals
- 🍕 **Extra Items** - View and register for extra items
- 📅 **Monthly Plans** - Manage monthly mess registrations
- ⚙️ **Preferences** - Control notification and meal settings
- 👤 **Profile** - View your user information
## Prerequisites
- **Node.js 18+** (Download from [nodejs.org](https://nodejs.org/))
- **Claude Desktop** (Download from [claude.ai/download](https://claude.ai/download))
- **Mess Portal API Key** (Get from [mess.iiit.ac.in](https://mess.iiit.ac.in))
## Installation
### 1. Clone and Install
```bash
git clone <your-repo-url>
cd mess-mcp
npm install
```
### 2. Get Your API Key
1. Log into https://mess.iiit.ac.in
2. Navigate to **Settings → API Keys**
3. Click **Create New Key**
4. Give it a name (e.g., "MCP Server") and set an expiry date
5. **Copy the key immediately** (it's only shown once!)
### 3. Configure Environment
Copy the example environment file and add your API key:
```bash
cp .env.example .env
```
Edit `.env` and replace `your-api-key-here` with your actual API key:
```env
MESS_API_KEY=your-actual-api-key-here
MESS_API_URL=https://mess.iiit.ac.in/api
```
### 4. Build the Project
```bash
npm run build
```
### 5. Configure Claude Desktop
Find your Claude Desktop config file:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS/Linux**: `~/Library/Application Support/Claude/claude_desktop_config.json`
Add the MCP server configuration:
```json
{
"mcpServers": {
"mess": {
"command": "node",
"args": ["/absolute/path/to/mess-mcp/dist/index.js"],
"env": {
"MESS_API_KEY": "your-actual-api-key-here",
"MESS_API_URL": "https://mess.iiit.ac.in/api"
}
}
}
}
```
**Important**: Replace `/absolute/path/to/mess-mcp` with the actual path to your project.
**Example paths:**
- Windows: `"args": ["C:/Users/YourName/mess-mcp/dist/index.js"]`
- macOS/Linux: `"args": ["/home/yourname/mess-mcp/dist/index.js"]`
### 6. Restart Claude Desktop
Close Claude Desktop completely (check system tray/menu bar) and reopen it. The MCP server will load automatically.
## Usage
Once set up, you can interact with the mess system using natural language in Claude Desktop:
### Example Conversations
**View Today's Menu:**
> "What's for lunch today?"
> "Show me today's menu at Kadamba Veg"
**Register for Meals:**
> "Register me for dinner tomorrow at Yuktahar"
> "Sign me up for breakfast on Friday at Palash"
**Cancel/Manage Registrations:**
> "Cancel my breakfast for tomorrow"
> "Show my registrations for this week"
> "Uncancel my lunch on December 5th"
**Check Bills:**
> "What's my mess bill this month?"
> "How much have I spent so far?"
**View Capacities:**
> "Is there space at Kadamba for dinner tonight?"
> "Show me available spots for lunch tomorrow"
**Submit Feedback:**
> "Rate today's lunch 4 stars with remark 'Good food'"
**Manage Preferences:**
> "Turn off meal reminder notifications"
> "Enable unregistered meal access"
## Available Tools
The MCP server exposes 30+ tools organized into categories:
### 🏢 Mess Information
- Get mess info, menus, rates, capacities, and timings
### 📝 Registrations
- View, create, cancel, and manage meal registrations
### 💰 Billing & Feedback
- Check bills, submit feedback, view ratings
### 🍕 Extra Items
- Browse and register for extra food items
### 📅 Monthly Plans
- Manage monthly mess subscriptions
### ⚙️ Configuration
- View/update preferences, check windows and limits
### 👤 User Profile
- View profile, reset QR token
## Development
### Project Structure
```
mess-mcp/
├── src/
│ ├── index.ts # Main MCP server entry point
│ ├── client.ts # HTTP client for Mess API
│ ├── types.ts # TypeScript type definitions
│ └── tools/
│ ├── auth.ts # User authentication tools
│ ├── mess.ts # Mess information tools
│ ├── registrations.ts # Registration management
│ ├── billing.ts # Bills and feedback
│ ├── extras.ts # Extra items
│ ├── monthly.ts # Monthly registrations
│ └── config.ts # Preferences and settings
├── dist/ # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── .env # Your config (not in git)
├── .env.example # Template for .env
└── README.md
```
### Scripts
- `npm run build` - Compile TypeScript to JavaScript
- `npm run dev` - Build and run in development mode
- `npm start` - Run the compiled server
## Troubleshooting
### "Command not found" or "node not found"
- Make sure Node.js is installed and in your system PATH
- Try using the full path to `node.exe` in the Claude config
### "Unauthorized" errors
- Verify your API key is correct in `.env` and Claude config
- Check if your API key has expired in the mess portal
### MCP server not loading
- Ensure the path in `claude_desktop_config.json` is absolute and correct
- Check Claude Desktop logs for errors
- Restart Claude Desktop after config changes
### Menu not showing items
- The menu might not be updated for the current week
- Try a different date or mess
## Security
- **Never commit `.env` file** - It contains your API key
- **Never share your API key** - It provides full access to your account
- The `.gitignore` file is configured to exclude sensitive files
- Rotate your API keys periodically in the mess portal settings
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request
## License
MIT
## Acknowledgments
Built for students of IIIT Hyderabad using the Mess Management System API.
## Support
For issues or questions:
- Open an issue on GitHub
- Check the [MCP Documentation](https://modelcontextprotocol.io)
- Review the [Mess Portal API docs](https://mess.iiit.ac.in)
