@lonzzi/tmdb-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,90 @@
+# TMDB MCP Server
+
+A Model Context Protocol (MCP) server that allows LLMs to search for movies and TV shows using the The Movie Database (TMDB) API.
+
+## Features
+
+- **Search Movies**: Find movies by title and get metadata including ID, URL, release date, rating, and overview.
+- **Search TV Shows**: Find TV shows by title and get metadata including ID, URL, first air date, rating, and overview.
+- **Direct Links**: Provides TMDb URLs for easy access to more details.
+- **Top Results**: Returns the top 5 most relevant results for each query.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) (v18 or higher)
+- A TMDB API Key. You can get one by creating an account on [themoviedb.org](https://www.themoviedb.org/) and applying for an API key in your account settings.
+
+## Installation
+
+1. Clone the repository:
+   ```bash
+   git clone <repository-url>
+   cd tmdb_mcp
+   ```
+
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+3. Build the project:
+   ```bash
+   npm run build
+   ```
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file in the root directory (or use `.env.example` as a template):
+
+```env
+TMDB_API_KEY=your_api_key_here
+```
+
+### MCP Client Configuration (e.g., Claude Desktop)
+
+To use this server with Claude Desktop, add it to your `claude_desktop_config.json`:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "tmdb": {
+      "command": "node",
+      "args": ["/absolute/path/to/tmdb_mcp/build/index.js"],
+      "env": {
+        "TMDB_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+*Note: Replace `/absolute/path/to/tmdb_mcp/` with the actual path to your project directory.*
+
+## Available Tools
+
+### `search_movies`
+Search for movies on TMDB by title.
+- **Arguments**:
+  - `query` (string, required): The movie title to search for.
+
+### `search_tv_shows`
+Search for TV shows on TMDB by title.
+- **Arguments**:
+  - `query` (string, required): The TV show title to search for.
+
+## Development
+
+### Running Tests
+```bash
+npm test
+```
+
+### Building
+```bash
+npm run build
+```

package/build/index.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const zod_1 = require("zod");
+const dotenv_1 = __importDefault(require("dotenv"));
+const tmdb_1 = require("./tmdb");
+dotenv_1.default.config();
+const API_KEY = process.env.TMDB_API_KEY;
+if (!API_KEY) {
+    console.error("TMDB_API_KEY environment variable is not set");
+    process.exit(1);
+}
+const server = new mcp_js_1.McpServer({
+    name: "tmdb-search",
+    version: "1.0.0",
+});
+server.registerTool("search_movies", {
+    description: "Search for movies on TMDB by title to get metadata like overview, release date, and rating",
+    inputSchema: zod_1.z.object({
+        query: zod_1.z.string().describe("The movie title to search for"),
+    }),
+}, async ({ query }) => {
+    try {
+        const result = await (0, tmdb_1.searchMovies)(API_KEY, query);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: error.message || "Unknown error occurred",
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.registerTool("search_tv_shows", {
+    description: "Search for TV shows on TMDB by title to get metadata like overview, first air date, and rating",
+    inputSchema: zod_1.z.object({
+        query: zod_1.z.string().describe("The TV show title to search for"),
+    }),
+}, async ({ query }) => {
+    try {
+        const result = await (0, tmdb_1.searchTvShows)(API_KEY, query);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: error.message || "Unknown error occurred",
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+const main = async () => {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+};
+main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});

package/build/tmdb.integration.test.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const tmdb_1 = require("./tmdb");
+const dotenv_1 = __importDefault(require("dotenv"));
+const path_1 = __importDefault(require("path"));
+// Load environment variables from .env file
+dotenv_1.default.config({ path: path_1.default.resolve(__dirname, "../.env") });
+const apiKey = process.env.TMDB_API_KEY;
+// Conditional describe: Only run if API key is present
+const describeIfApiKey = apiKey ? describe : describe.skip;
+describeIfApiKey("TMDB Integration Tests", () => {
+    // Increase timeout for real network requests
+    jest.setTimeout(30000);
+    it("should find 'Inception'", async () => {
+        console.log("Querying TMDB for 'Inception'...");
+        const results = await (0, tmdb_1.searchMovies)(apiKey, "Inception");
+        expect(results.length).toBeGreaterThan(0);
+        const inception = results.find(m => m.title === "Inception");
+        expect(inception).toBeDefined();
+        expect(inception?.id).toBe(27205); // TMDB ID for Inception
+    });
+    it("should find 'Breaking Bad'", async () => {
+        console.log("Querying TMDB for 'Breaking Bad'...");
+        const results = await (0, tmdb_1.searchTvShows)(apiKey, "Breaking Bad");
+        expect(results.length).toBeGreaterThan(0);
+        const breakingBad = results.find(show => show.name === "Breaking Bad");
+        expect(breakingBad).toBeDefined();
+        expect(breakingBad?.id).toBe(1396); // TMDB ID for Breaking Bad
+    });
+    it("should find 'The Matrix'", async () => {
+        console.log("Querying TMDB for 'The Matrix'...");
+        const results = await (0, tmdb_1.searchMovies)(apiKey, "The Matrix");
+        expect(results.length).toBeGreaterThan(0);
+        const matrix = results.find(m => m.title === "The Matrix");
+        expect(matrix).toBeDefined();
+        expect(matrix?.id).toBe(603); // TMDB ID for The Matrix
+    });
+    it("should find 'One Punch Man'", async () => {
+        console.log("Querying TMDB for 'One Punch Man'...");
+        const results = await (0, tmdb_1.searchTvShows)(apiKey, "One Punch Man");
+        expect(results.length).toBeGreaterThan(0);
+        const opm = results.find(show => show.name === "One-Punch Man");
+        expect(opm).toBeDefined();
+        expect(opm?.id).toBe(63926); // TMDB ID for One Punch Man
+    });
+    it("should return empty array for gibberish query", async () => {
+        const results = await (0, tmdb_1.searchMovies)(apiKey, "asdfjkl;qweruiop1234");
+        expect(results).toEqual([]);
+    });
+});
+if (!apiKey) {
+    test("Skipping integration tests", () => {
+        console.warn("TMDB_API_KEY not found in .env. Skipping integration tests.");
+    });
+}

package/build/tmdb.js

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchTvShows = exports.searchMovies = void 0;
+const axios_1 = __importDefault(require("axios"));
+const searchMovies = async (apiKey, query) => {
+    if (!query) {
+        throw new Error("Query argument is required");
+    }
+    try {
+        const response = await axios_1.default.get("https://api.themoviedb.org/3/search/movie", {
+            params: {
+                api_key: apiKey,
+                query: query,
+                language: "en-US",
+                page: 1,
+            },
+        });
+        return response.data.results.slice(0, 5); // Limit to top 5 results
+    }
+    catch (error) {
+        if (axios_1.default.isAxiosError(error)) {
+            throw new Error(`TMDB API Error: ${error.message}`);
+        }
+        throw error;
+    }
+};
+exports.searchMovies = searchMovies;
+const searchTvShows = async (apiKey, query) => {
+    if (!query) {
+        throw new Error("Query argument is required");
+    }
+    try {
+        const response = await axios_1.default.get("https://api.themoviedb.org/3/search/tv", {
+            params: {
+                api_key: apiKey,
+                query: query,
+                language: "en-US",
+                page: 1,
+            },
+        });
+        return response.data.results.slice(0, 5);
+    }
+    catch (error) {
+        if (axios_1.default.isAxiosError(error)) {
+            throw new Error(`TMDB API Error: ${error.message}`);
+        }
+        throw error;
+    }
+};
+exports.searchTvShows = searchTvShows;

package/build/tmdb.test.js

@@ -0,0 +1,108 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const axios_1 = __importDefault(require("axios"));
+const tmdb_1 = require("./tmdb");
+jest.mock("axios");
+const mockedAxios = axios_1.default;
+describe("searchMovies", () => {
+    const apiKey = "test-api-key";
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+    it("should return movie results and call API with correct parameters", async () => {
+        const mockMovies = [
+            {
+                id: 1,
+                title: "Test Movie",
+                overview: "Test Overview",
+                release_date: "2023-01-01",
+                vote_average: 8.0,
+            },
+        ];
+        const mockResponse = {
+            data: {
+                results: mockMovies,
+            },
+        };
+        mockedAxios.get.mockResolvedValue(mockResponse);
+        const query = "Test Query";
+        const result = await (0, tmdb_1.searchMovies)(apiKey, query);
+        expect(result).toEqual(mockMovies);
+        expect(mockedAxios.get).toHaveBeenCalledWith("https://api.themoviedb.org/3/search/movie", {
+            params: {
+                api_key: apiKey,
+                query: query,
+                language: "en-US",
+                page: 1,
+            },
+        });
+    });
+    it("should return an empty array when result list is empty", async () => {
+        mockedAxios.get.mockResolvedValue({
+            data: {
+                results: [],
+            },
+        });
+        const result = await (0, tmdb_1.searchMovies)(apiKey, "Nonexistent Movie");
+        expect(result).toEqual([]);
+    });
+    it("should throw an error if the query is empty", async () => {
+        await expect((0, tmdb_1.searchMovies)(apiKey, "")).rejects.toThrow("Query argument is required");
+    });
+    it("should handle API errors", async () => {
+        const errorMessage = "Network Error";
+        mockedAxios.get.mockRejectedValue({
+            isAxiosError: true,
+            message: errorMessage,
+        });
+        // We need to mock isAxiosError since we are using it in the catch block
+        axios_1.default.isAxiosError = jest.fn().mockReturnValue(true);
+        await expect((0, tmdb_1.searchMovies)(apiKey, "Error Movie")).rejects.toThrow(`TMDB API Error: ${errorMessage}`);
+    });
+});
+describe("searchTvShows", () => {
+    const apiKey = "test-api-key";
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+    it("should return TV show results and call API with correct parameters", async () => {
+        const mockShows = [
+            {
+                id: 101,
+                name: "Test Show",
+                overview: "Test Overview",
+                first_air_date: "2023-01-01",
+                vote_average: 7.5,
+            },
+        ];
+        const mockResponse = {
+            data: {
+                results: mockShows,
+            },
+        };
+        mockedAxios.get.mockResolvedValue(mockResponse);
+        const query = "Test Show Query";
+        const result = await (0, tmdb_1.searchTvShows)(apiKey, query);
+        expect(result).toEqual(mockShows);
+        expect(mockedAxios.get).toHaveBeenCalledWith("https://api.themoviedb.org/3/search/tv", {
+            params: {
+                api_key: apiKey,
+                query: query,
+                language: "en-US",
+                page: 1,
+            },
+        });
+    });
+    it("should return an empty array when result list is empty", async () => {
+        mockedAxios.get.mockResolvedValue({
+            data: {
+                results: [],
+            },
+        });
+        const result = await (0, tmdb_1.searchTvShows)(apiKey, "Nonexistent Show");
+        expect(result).toEqual([]);
+    });
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@lonzzi/tmdb-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for searching movies on TMDB",
+  "main": "build/index.js",
+  "bin": {
+    "tmdb-mcp": "build/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node build/index.js",
+    "test": "jest",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "build"
+  ],
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "axios": "^1.13.2",
+    "dotenv": "^16.6.1",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@types/axios": "^0.14.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.0.0"
+  }
+}