# IMDB MCP Server
A cloud-runnable JSON-RPC service that provides access to IMDB data. Designed to work with LLMs via the MCP (Model Context Protocol).
## How It Works
1. **LLM Configuration**: Add the MCP server URL to your LLM's configuration
2. **Discovery**: The LLM queries the server URL to understand available tools
3. **Query**: The LLM sends JSON-RPC requests to fetch IMDB data
4. **Response**: The server returns structured data that the LLM interprets and explains to users
## Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | HTML documentation (human-readable) |
| `/info` | GET | Service information (JSON) |
| `/jsonrpc` | POST | JSON-RPC 2.0 endpoint |
| `/mcp` | POST | MCP protocol endpoint for LLM tool calling |
| `/health` | GET | Health check for cloud deployments |
## Available Tools
| Tool | Description | Parameters |
|------|-------------|------------|
| `search_movies` | Search movies by title | `query`, `limit` |
| `get_movie_details` | Get full movie info | `movie_id` |
| `search_people` | Search actors/directors | `query`, `limit` |
| `get_person_details` | Get person info/filmography | `person_id` |
| `get_top_250_movies` | Get IMDB Top 250 | `limit` |
| `get_movie_cast` | Get cast of a movie | `movie_id`, `limit` |
## JSON-RPC Usage
Send a POST request to `/jsonrpc`:
```json
{
"jsonrpc": "2.0",
"method": "search_movies",
"params": {"query": "The Matrix", "limit": 5},
"id": 1
}
```
Response:
```json
{
"jsonrpc": "2.0",
"result": [
{"id": "0133093", "title": "The Matrix", "year": 1999},
{"id": "0234215", "title": "The Matrix Reloaded", "year": 2003}
],
"id": 1
}
```
## LLM MCP Configuration
Add to your LLM's MCP server configuration:
```json
{
"mcpServers": {
"imdb": {
"url": "https://your-deployed-url.com/mcp",
"transport": "http"
}
}
}
```
## Local Development
### Run locally
```bash
pip install -r requirements.txt
python app.py
```
Server runs at `http://localhost:8080`
### Run with Docker
```bash
docker build -t imdb-mcp .
docker run -p 8080:8080 imdb-mcp
```
## Cloud Deployment
### Cloud Foundry
```bash
cf push
```
Uses `manifest.yaml` configuration.
### SAP BTP (Cloud Foundry)
```bash
# Build MTA archive
mbt build
# Deploy
cf deploy mta_archives/imdb-mcp-server_1.0.0.mtar
```
Uses `mta.yaml` configuration.
### Heroku
```bash
heroku create imdb-mcp-server
git push heroku main
```
Uses `Procfile` and `runtime.txt`.
### Docker (Any Cloud)
```bash
# Build
docker build -t imdb-mcp .
# Run
docker run -p 8080:8080 imdb-mcp
# Push to registry
docker tag imdb-mcp your-registry/imdb-mcp:latest
docker push your-registry/imdb-mcp:latest
```
### Google Cloud Run
```bash
gcloud run deploy imdb-mcp \
--source . \
--platform managed \
--allow-unauthenticated
```
### AWS App Runner / ECS
Use the Dockerfile with your preferred AWS container service.
## Project Structure
```
imdb-mcp/
├── app.py # FastAPI JSON-RPC server
├── imdb_backend.py # Cinemagoer wrapper
├── server.py # FastMCP server (for local MCP)
├── requirements.txt # Python dependencies
├── pyproject.toml # Project metadata
├── Dockerfile # Container image
├── Procfile # Heroku/PaaS process file
├── runtime.txt # Python version
├── manifest.yaml # Cloud Foundry manifest
├── mta.yaml # SAP BTP MTA descriptor
├── .dockerignore # Docker ignore patterns
└── .cfignore # Cloud Foundry ignore patterns
```
## Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | 8080 | Server port |
## Notes
- Cinemagoer queries IMDB via web scraping, responses may be slower than API-based solutions
- For non-commercial use only (per IMDB terms of service)
- No API key required
