Indian Movies MCP Agent 🎬

A Model Context Protocol (MCP) agent that provides Indian movie recommendations directly within Claude Desktop. Get personalized Bollywood, Tollywood, and regional cinema suggestions with intelligent filtering by genre, language, rating, and release year.

🎯 What This Does

This MCP agent adds three powerful tools to your Claude Desktop:

• Smart Recommendations: Filter movies by genre, language, rating, or year

• Movie Search: Find detailed information about specific films

• Random Discovery: Get surprise recommendations from curated Indian cinema

Related MCP server: Filmladder MCP Server

📋 Prerequisites

Before you begin, ensure you have:

• macOS (this guide is Mac-specific)

• Node.js version 18 or higher (Download here)

• Claude Desktop app (Download here)

• Terminal access

• Text editor (VS Code, TextEdit, etc.)

Check Your Node.js Version

node --version

If you see v18.0.0 or higher, you're good to go!

🚀 Quick Start (5 Minutes)

Step 1: Clone and Setup

# Clone the repository
git clone https://github.com/yourusername/indian-movies-mcp.git
cd indian-movies-mcp

# Install dependencies
npm install

# Test the server (optional)
npm start

If testing, you should see: Indian Movies MCP server running on stdio Press Ctrl+C to stop the test.

Step 2: Get Your Project Path

# Get the full path to your project
pwd

Copy this path! You'll need it in the next step. Example output: /Users/john/Documents/indian-movies-mcp

Step 3: Configure Claude Desktop

Option A: Create Config File via Terminal (Recommended)

# Navigate to Claude's config directory
cd ~/Library/Application\ Support/Claude/

# Create the config file
cat > claude_desktop_config.json << 'EOF'
{
  "mcpServers": {
    "indian-movies": {
      "command": "node",
      "args": ["REPLACE_WITH_YOUR_PATH/index.js"]
    }
  }
}
EOF

Important: Replace REPLACE_WITH_YOUR_PATH with the path you copied from Step 2.

Option B: Create Config File Manually

1. Open Finder

2. Press Cmd + Shift + G

3. Go to: ~/Library/Application Support/Claude/

4. Create a new file named: claude_desktop_config.json

5. Copy and paste this content, replacing the path:

{
  "mcpServers": {
    "indian-movies": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/path/to/indian-movies-mcp/index.js"]
    }
  }
}

Step 4: Connect to Claude Desktop

1. Completely quit Claude Desktop (don't just close the window)

2. Restart Claude Desktop

3. Wait 10-15 seconds for the connection to establish

Step 5: Test It!

In Claude Desktop, try asking:

• "Recommend some Hindi comedy movies"

• "Find action movies with rating above 8"

• "Search for the movie Dangal"

• "Give me a random Indian movie recommendation"

📖 Detailed Installation Guide

For Complete Beginners

What is Node.js?

Node.js lets you run JavaScript on your computer (outside of a web browser). We need it to run our movie recommendation server.

Installing Node.js

1. Go to nodejs.org

2. Download the LTS version (Long Term Support)

3. Run the installer

4. Restart your Terminal after installation

What is npm?

npm (Node Package Manager) comes with Node.js and helps install code libraries. Think of it like an app store for code.

Understanding the File Structure

indian-movies-mcp/
├── package.json          # Project configuration and dependencies
├── index.js              # Main MCP server code
├── README.md             # This file
└── node_modules/         # Installed dependencies (created by npm install)

🛠️ Manual Setup (Alternative Method)

If you prefer to set up everything from scratch:

1. Create Project Directory

mkdir indian-movies-mcp
cd indian-movies-mcp

2. Create package.json

cat > package.json << 'EOF'
{
  "name": "indian-movies-mcp",
  "version": "1.0.0",
  "description": "MCP server for Indian movie recommendations",
  "main": "index.js",
  "type": "module",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^0.4.0"
  }
}
EOF

3. Install Dependencies

npm install

4. Create the Server File

Copy the index.js content from this repository into a new file in your project directory.

5. Continue with Step 2 from Quick Start

🎭 Available Movie Tools

1. Get Movie Recommendations

Usage: "Recommend movies with specific criteria"

Parameters:

• genre: Comedy, Drama, Action, Thriller, etc.

• language: Hindi, Telugu, Tamil, etc.

• min_rating: Minimum rating (0-10)

• year_after: Movies released after this year

Examples:

• "Show me Hindi comedies"

• "Find action movies with rating above 8"

• "Recommend movies from 2015 onwards"

2. Search Movie

Usage: "Search for a specific movie"

Parameters:

• title: Movie title to search for

Examples:

• "Tell me about 3 Idiots"

• "Search for Baahubali"

3. Random Movie

Usage: "Get a surprise recommendation"

Examples:

• "Suggest a random Indian movie"

• "Give me a random recommendation"

🎬 Current Movie Database

The agent includes these popular Indian films:

Hindi Cinema:

• 3 Idiots (2009) - Comedy/Drama

• Dangal (2016) - Biography/Drama/Sport

• Taare Zameen Par (2007) - Drama/Family

• Zindagi Na Milegi Dobara (2011) - Adventure/Comedy

• And more...

Regional Cinema:

• Baahubali 2 (2017) - Telugu Action/Drama

• Various Tamil and other regional films

📊 Enhanced Logging for MCP Protocol Learning

This version includes comprehensive logging to help you understand the Model Context Protocol (MCP) communication between Claude and the MCP agent. Perfect for learning how MCP works under the hood!

🔍 What Gets Logged

The enhanced logging system captures:

• Protocol Messages: All requests and responses between Claude and the MCP server

• Tool Calls: Detailed information about which tools are called and with what parameters

• Data Filtering: Step-by-step filtering process for movie recommendations

• Error Handling: Comprehensive error logging with stack traces

• Server Lifecycle: Connection, disconnection, and heartbeat messages

📁 Log File Location

Logs are written to: mcp-server.log in your project directory

🚀 Viewing Logs in Real-Time

Option 1: Terminal Logs (Live Output)

Start the server and watch logs in your terminal:

cd /path/to/your/indian-movies-mcp
npm start

You'll see live logs like:

[MCP INFO] === MCP Server Starting ===
[MCP INFO] Movie database loaded
[MCP INFO] Server instance created
[MCP INFO] === MCP SERVER CONNECTED AND READY ===

Option 2: Follow Log File (Recommended for Learning)

In a separate terminal window, watch the detailed log file:

# Navigate to your project directory
cd /path/to/your/indian-movies-mcp

# Follow the log file in real-time
tail -f mcp-server.log

Option 3: View Complete Log History

# View all logs from the beginning
cat mcp-server.log

# View recent logs with line numbers
tail -100 mcp-server.log | nl

# Search for specific events
grep "TOOL CALL" mcp-server.log
grep "ERROR" mcp-server.log

🎯 Understanding MCP Protocol Flow

When you interact with Claude, watch the logs to see this flow:

1. Initialization: Claude connects to your MCP server

2. Tool Discovery: Claude asks "what tools do you have?"

3. Tool Execution: Claude calls specific tools with parameters

4. Data Processing: Your server processes and returns results

Example Log Sequence

When you ask Claude "Recommend Hindi comedies", you'll see:

[2024-07-20T10:30:15.123Z] [INFO] === RECEIVED LIST TOOLS REQUEST ===
[2024-07-20T10:30:15.124Z] [INFO] Sending tools response: {
  "tools": [...]
}

[2024-07-20T10:30:15.200Z] [INFO] === RECEIVED TOOL CALL REQUEST ===
[2024-07-20T10:30:15.201Z] [INFO] Tool name: get_movie_recommendations
[2024-07-20T10:30:15.202Z] [INFO] Tool arguments: {
  "genre": "Comedy",
  "language": "Hindi"
}

[2024-07-20T10:30:15.203Z] [INFO] Processing movie recommendations request
[2024-07-20T10:30:15.204Z] [INFO] Starting with movies: {"count": 10}
[2024-07-20T10:30:15.205Z] [INFO] Filtering by genre: Comedy
[2024-07-20T10:30:15.206Z] [INFO] After genre filter: {"count": 4}
[2024-07-20T10:30:15.207Z] [INFO] Filtering by language: Hindi
[2024-07-20T10:30:15.208Z] [INFO] After language filter: {"count": 3}

🔬 Learning MCP Protocol Concepts

Use the logs to understand these MCP concepts:

1. Tool Discovery

Watch for LIST TOOLS REQUEST to see how Claude discovers available tools:

grep -A 10 "LIST TOOLS REQUEST" mcp-server.log

2. Tool Schemas

See how input validation works by examining tool call parameters:

grep -A 5 "Tool arguments" mcp-server.log

3. Error Handling

Understand MCP error handling by triggering errors:

# In Claude, try: "Search for a movie that doesn't exist"
grep "ERROR" mcp-server.log

4. Data Flow

Track data transformation through the logging:

grep -E "(Starting with|After.*filter)" mcp-server.log

🛠️ Debugging with Logs

Finding Connection Issues

# Check if server started properly
grep "SERVER CONNECTED" mcp-server.log

# Look for connection errors
grep -i "error\|failed" mcp-server.log

Analyzing Tool Performance

# See which tools are called most
grep "Tool called:" mcp-server.log | sort | uniq -c

# Check tool execution times (manual timing from timestamps)
grep -E "Tool called:|Sending.*response" mcp-server.log

Understanding Request Flow

# See the complete request-response cycle
grep -E "RECEIVED.*REQUEST|Sending.*response" mcp-server.log

📚 Log Levels Explained

• INFO: Normal operations (tool calls, data processing)

• WARN: Potential issues that don't break functionality

• ERROR: Actual errors that need attention

• DEBUG: Verbose information for detailed analysis

🎓 Learning Exercises

Try these exercises to understand MCP better:

Exercise 1: Basic Protocol Flow

1. Start the server and watch logs

2. Ask Claude: "What movie tools do you have?"

3. Observe the tool discovery protocol in the logs

Exercise 2: Parameter Validation

1. Ask Claude: "Recommend movies" (no parameters)

2. Ask Claude: "Recommend Hindi comedies" (with parameters)

3. Compare how parameters are handled in the logs

Exercise 3: Error Handling

1. Temporarily break the code (add a syntax error)

2. Watch how errors propagate through the MCP protocol

3. Fix the code and observe recovery

Exercise 4: Data Filtering

1. Ask for complex filters: "Hindi action movies from 2015 with rating above 8"

2. Watch the step-by-step filtering process in the logs

3. Understand how data flows through the system

📁 Log File Management

The log file can grow large over time. Manage it with:

# Check log file size
ls -lh mcp-server.log

# Archive old logs
mv mcp-server.log mcp-server-$(date +%Y%m%d).log

# Clear current logs (server will create new file)
> mcp-server.log

# Rotate logs automatically (optional)
# Add to your crontab for daily rotation:
# 0 0 * * * cd /path/to/indian-movies-mcp && mv mcp-server.log logs/mcp-server-$(date +\%Y\%m\%d).log 2>/dev/null

🎯 Pro Tips for MCP Learning

1. Use Two Terminals: One for server logs, one for file logs

2. Timestamps: Correlate Claude requests with log timestamps

3. JSON Formatting: Use jq to format JSON in logs: cat mcp-server.log | grep "Tool arguments" | jq

4. Pattern Matching: Learn to spot patterns in MCP communication

5. Error Simulation: Intentionally trigger errors to understand error handling

🔧 Troubleshooting

MCP Server Not Connecting

Problem: Claude Desktop doesn't recognize the MCP server

Solutions:

1. Check the config file path:

   ls ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. Verify the server path is absolute:

   # Your path should start with / like this:
   /Users/john/Documents/indian-movies-mcp/index.js

3. Test your server manually:

   cd /path/to/your/indian-movies-mcp
   npm start

4. Completely restart Claude Desktop:

   • Quit Claude Desktop (Cmd+Q)

   • Wait 5 seconds

   • Restart Claude Desktop

Node.js or npm Issues

Problem: command not found: node or command not found: npm

Solution:

1. Install Node.js from nodejs.org

2. Restart your Terminal

3. Verify installation: node --version

Permission Issues

Problem: Permission denied errors

Solution:

# Make the script executable
chmod +x index.js

# If you have permission issues with the config directory
sudo chown -R $(whoami) ~/Library/Application\ Support/Claude/

Config File Issues

Problem: JSON syntax errors

Solution:

1. Validate your JSON at jsonlint.com

2. Common issues:

   • Missing commas

   • Incorrect quotes (use " not ')

   • Missing closing brackets

Logging Issues

Problem: No logs appearing in mcp-server.log

Solution:

1. Check if the server is running:

   ps aux | grep "node.*index.js"

2. Verify logging.js is properly imported:

   grep "from './logging.js'" index.js

3. Check file permissions:

   ls -la mcp-server.log
   # If file doesn't exist, it will be created automatically

4. Test logging manually:

   node -e "import('./logging.js').then(({log}) => log('Test message'))"

Problem: Logs are too verbose or cluttering terminal

Solution:

1. Use only file logging by redirecting stderr:

   npm start 2>/dev/null

2. Filter logs by level:

   grep "\[ERROR\]" mcp-server.log
   grep "\[WARN\]" mcp-server.log
   grep "\[INFO\]" mcp-server.log

3. Reduce log verbosity by commenting out detailed logs in index.js

Problem: Log file growing too large

Solution:

1. Set up log rotation:

   # Create logs directory
   mkdir -p logs
   
   # Rotate current log
   mv mcp-server.log logs/mcp-server-backup-$(date +%Y%m%d-%H%M%S).log

2. Implement size-based rotation:

   # Check file size and rotate if > 10MB
   if [ $(wc -c < mcp-server.log) -gt 10485760 ]; then
     mv mcp-server.log logs/mcp-server-$(date +%Y%m%d-%H%M%S).log
   fi

Problem: Cannot correlate Claude actions with logs

Solution:

1. Use precise timestamps:

   # Note the time when you make a request in Claude
   date
   # Then check logs around that time
   grep "2024-07-20T10:30" mcp-server.log

2. Add request markers in Claude:

   • Ask Claude: "Search for test-marker-movie"

   • Look for this unique term in logs to identify your session

3. Use unique test queries:

   # Instead of "recommend movies", use:
   # "recommend movies with unique-identifier-12345"
   # Then search logs for "unique-identifier-12345"

🔄 Updating the Movie Database

Want to add more movies? Edit the indianMovies array in index.js:

const indianMovies = [
  // Add your movie like this:
  {
    title: "Your Movie Title",
    year: 2023,
    genre: ["Comedy", "Drama"],
    language: "Hindi",
    rating: 8.0,
    director: "Director Name",
    description: "Brief description of the movie."
  },
  // ... existing movies
];

After adding movies:

1. Save the file

2. Restart Claude Desktop

3. Test with new movie searches

🤝 Contributing

Want to improve this MCP agent?

1. Fork this repository

2. Create a feature branch: git checkout -b feature-name

3. Add more movies, improve filtering, or add new tools

4. Commit your changes: git commit -m "Add feature"

5. Push to your branch: git push origin feature-name

6. Create a Pull Request

Ideas for Contributions

• Add more regional Indian films

• Include movie posters or trailers

• Add director/actor filtering

• Include streaming platform availability

• Add movie reviews or ratings from multiple sources

📝 License

MIT License - feel free to use and modify!

🆘 Getting Help

If you run into issues:

1. Check the troubleshooting section above

2. Create an issue on this GitHub repository

3. Include:

   • Your macOS version

   • Node.js version (node --version)

   • Error messages

   • Your config file (remove personal paths)

🎉 What's Next?

Once you have this working, you can:

• Build other MCP agents for different domains

• Expand this agent with more Indian cinema data

• Create agents for other movie industries

• Add real-time data from movie APIs

Happy movie watching! 🍿