# Directory Structure
```
├── .github
│ └── workflows
│ └── claude.yml
├── .gitignore
├── Dockerfile
├── LICENSE
├── package.json
├── README.md
├── server-http.js
├── smithery.yaml
├── src
│ ├── index.ts
│ └── server-http.js
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
node_modules/
dist/
.env
*.log
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
[](https://mseep.ai/app/laksh-star-mcp-server-tmdb)
# TMDB MCP Server
[](https://smithery.ai/server/@Laksh-star/mcp-server-tmdb)
This MCP server integrates with The Movie Database (TMDB) API to provide movie information, search capabilities, and recommendations.
<a href="https://glama.ai/mcp/servers/g3nl1a0n25"><img width="380" height="200" src="https://glama.ai/mcp/servers/g3nl1a0n25/badge" alt="mcp-server-tmdb MCP server" /></a>
[](https://deepwiki.com/Laksh-star/mcp-server-tmdb)
## Prerequisites
Before installing and running the TMDB MCP server, ensure you have the following prerequisites installed and configured:
### Required software
- **Node.js**
- Version 18.0.0 or higher
- Download from [Node.js official website](https://nodejs.org/)
- Verify installation: `node --version`
- **npm (Node Package Manager)**
- Version 8.0.0 or higher (comes with Node.js)
- Verify installation: `npm --version`
- **TypeScript**
- Will be installed as a project dependency
- Can be installed globally: `npm install -g typescript`
- Verify installation: `tsc --version`
### Required accounts & API keys
- **TMDB account**
- Free account at [TMDB](https://www.themoviedb.org/)
- API key from TMDB dashboard
- API access must be approved by TMDB
- **Claude desktop application**
- Latest version installed
- Access to modify configuration files
### System requirements
- **Operating systems**
- macOS (10.15 or later)
- Linux (modern distributions)
- **Hardware requirements**
- Minimum 4GB RAM
- 1GB free disk space
- Stable internet connection
### Development environment
For the best development experience, we recommend:
- A code editor with TypeScript support (e.g., VS Code)
- Terminal access
- Git (for version control)
## Features
### Tools
- **search_movies**
- Search for movies by title or keywords
- Input: `query` (string): Search query
- Returns: List of movies with titles, release years, IDs, ratings, and overviews
- Example: Search for movies about space exploration
- **get_recommendations**
- Get movie recommendations based on a movie ID
- Input: `movieId` (string): TMDB movie ID
- Returns: Top 5 recommended movies with details
- Example: Get recommendations based on movie ID 550 (Fight Club)
- **get_trending**
- Get trending movies for a specified time window
- Input: `timeWindow` (string): Either "day" or "week"
- Returns: Top 10 trending movies with details
- Example: Get today's trending movies
### Resources
The server provides access to TMDB movie information:
- **Movies** (`tmdb:///movie/<movie_id>`)
- Comprehensive movie details including:
- Title and release date
- Rating and overview
- Genres
- Poster URL
- Cast information (top 5 actors)
- Director
- Selected reviews
- All data is returned in JSON format
## Getting started
1. Get a TMDB API key:
- Sign up at [TMDB](https://www.themoviedb.org/)
- Go to your account settings
- Navigate to the API section
- Request an API key for developer use
2. Clone and set up the project:
```bash
git clone [repository-url]
cd mcp-server-tmdb
npm install
```
3. Build the server:
```bash
npm run build
```
4. Set up your environment variable:
```bash
export TMDB_API_KEY=your_api_key_here
```
### Usage with Claude Desktop
To integrate this server with Claude Desktop, add the following to your app's server configuration file (located at `~/Library/Application Support/Claude/config.json`):
```json
{
"mcpServers": {
"tmdb": {
"command": "/full/path/to/dist/index.js",
"env": {
"TMDB_API_KEY": "your_api_key_here"
}
}
}
}
```
Replace `/full/path/to` with the actual path to your project directory.
### Installing via Smithery
To install TMDB Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@Laksh-star/mcp-server-tmdb):
```bash
npx -y @smithery/cli install @Laksh-star/mcp-server-tmdb --client claude
```
## Example usage
Once the server is running with Claude Desktop, you can use commands like:
1. Search for movies:
```
"Search for movies about artificial intelligence"
```
2. Get trending movies:
```
"What are the trending movies today?"
"Show me this week's trending movies"
```
3. Get movie recommendations:
```
"Get movie recommendations based on movie ID 550"
```
4. Get movie details:
```
"Tell me about the movie with ID 550"
```
## Error handling
The server includes comprehensive error handling for:
- Invalid API keys
- Network errors
- Invalid movie IDs
- Malformed requests
Error messages will be returned in a user-friendly format through Claude Desktop.
## Development
To watch for changes during development:
```bash
npm run watch
```
## License
This MCP server is licensed under the MIT License. See the LICENSE file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
{
"compilerOptions": {
"target": "ES2020",
"module": "ES2020",
"moduleResolution": "node",
"outDir": "./dist",
"rootDir": "src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": [
"src/**/*.ts"
]
}
```
--------------------------------------------------------------------------------
/Dockerfile:
--------------------------------------------------------------------------------
```dockerfile
# Generated by https://smithery.ai. See: https://smithery.ai/docs/config#dockerfile
FROM node:lts-alpine
# Create app directory
WORKDIR /usr/src/app
# Install app dependencies
# A wildcard is used to ensure both package.json and package-lock.json are copied
COPY package*.json ./
# Install dependencies (ignoring prepare scripts to avoid auto-build if necessary)
RUN npm install --ignore-scripts
# Build the project explicitly
COPY tsconfig.json ./
COPY src ./src
RUN npm run build
# Bundle app source
# Expose a volume if necessary, but here we assume a command line tool
# Default command
CMD ["node", "dist/index.js"]
```
--------------------------------------------------------------------------------
/.github/workflows/claude.yml:
--------------------------------------------------------------------------------
```yaml
name: Claude Issue Comment Response
on:
issue_comment:
types: [created]
permissions:
id-token: write # Required for OIDC token access
issues: write # Required for commenting on issues
pull-requests: write # Optional, if Claude interacts with PRs
jobs:
claude-respond:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run Claude Code Action
uses: anthropics/claude-code-action@beta
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
direct_prompt: "Respond to comments mentioning '@claude' with relevant assistance or code suggestions."
```
--------------------------------------------------------------------------------
/smithery.yaml:
--------------------------------------------------------------------------------
```yaml
# Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml
startCommand:
type: stdio
configSchema:
# JSON Schema defining the configuration options for the MCP.
type: object
required:
- tmdbApiKey
properties:
tmdbApiKey:
type: string
description: The TMDB API key from your TMDB account
commandFunction:
# A JS function that produces the CLI command based on the given config to start the MCP on stdio.
|-
(config) => ({ command: 'node', args: ['dist/index.js'], env: { TMDB_API_KEY: config.tmdbApiKey } })
exampleConfig:
tmdbApiKey: your_tmdb_api_key_here
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
{
"name": "mcp-server-tmdb",
"version": "1.0.0",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"build": "tsc && shx chmod +x dist/*.js",
"prepare": "npm run build",
"watch": "tsc --watch"
},
"keywords": [],
"author": "",
"license": "ISC",
"description": "",
"dependencies": {
"@modelcontextprotocol/sdk": "^1.0.3",
"node-fetch": "^3.3.2"
},
"devDependencies": {
"@types/node": "^22.10.1",
"@types/node-fetch": "^2.6.12",
"shx": "^0.3.4",
"typescript": "^5.7.2"
},
"type": "module",
"bin": {
"mcp-server-tmdb": "dist/index.js"
}
}
```
--------------------------------------------------------------------------------
/server-http.js:
--------------------------------------------------------------------------------
```javascript
#!/usr/bin/env node
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import fetch from 'node-fetch';
import express from 'express';
import cors from 'cors';
const app = express();
app.use(cors());
app.use(express.json());
const server = new Server(
{
name: 'mcp-server-tmdb',
version: '1.0.0',
},
{
capabilities: {
tools: {},
},
}
);
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
{
name: 'search_movies',
description: 'Search for movies by title or keywords',
inputSchema: {
type: 'object',
properties: {
query: {
type: 'string',
description: 'Search query',
},
},
required: ['query'],
},
},
{
name: 'get_recommendations',
description: 'Get movie recommendations based on a movie ID',
inputSchema: {
type: 'object',
properties: {
movieId: {
type: 'string',
description: 'TMDB movie ID',
},
},
required: ['movieId'],
},
},
{
name: 'get_trending',
description: 'Get trending movies for a specified time window',
inputSchema: {
type: 'object',
properties: {
timeWindow: {
type: 'string',
description: 'Time window: "day" or "week"',
enum: ['day', 'week'],
},
},
required: ['timeWindow'],
},
},
],
};
});
server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
const apiKey = process.env.TMDB_API_KEY;
if (!apiKey) {
throw new Error('TMDB_API_KEY environment variable is required');
}
try {
switch (name) {
case 'search_movies': {
const response = await fetch(
`https://api.themoviedb.org/3/search/movie?api_key=${apiKey}&query=${encodeURIComponent(args.query)}`
);
const data = await response.json();
return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
}
case 'get_recommendations': {
const response = await fetch(
`https://api.themoviedb.org/3/movie/${args.movieId}/recommendations?api_key=${apiKey}`
);
const data = await response.json();
return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
}
case 'get_trending': {
const response = await fetch(
`https://api.themoviedb.org/3/trending/movie/${args.timeWindow}?api_key=${apiKey}`
);
const data = await response.json();
return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
}
default:
throw new Error(`Unknown tool: ${name}`);
}
} catch (error) {
throw new Error(`Tool execution failed: ${error.message}`);
}
});
// Create SSE transport
const transport = new SSEServerTransport('/messages', server);
// Set up routes
app.get('/sse', async (req, res) => {
return transport.handleSSEConnection(req, res);
});
app.post('/messages', async (req, res) => {
return transport.handlePostRequest(req, res);
});
app.get('/', (req, res) => {
res.json({
name: 'TMDB MCP Server',
version: '1.0.0',
status: 'running',
endpoints: {
sse: '/sse',
messages: '/messages'
}
});
});
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
console.log(`TMDB MCP Server running on port ${PORT}`);
console.log(`SSE endpoint: http://localhost:${PORT}/sse`);
console.log(`Messages endpoint: http://localhost:${PORT}/messages`);
});
```
--------------------------------------------------------------------------------
/src/server-http.js:
--------------------------------------------------------------------------------
```javascript
#!/usr/bin/env node
import express from "express";
import { randomUUID } from "node:crypto";
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
import fetch from 'node-fetch';
import cors from 'cors';
const app = express();
app.use(cors());
app.use(express.json());
// Map to store transports by session ID
const transports = {};
// Create MCP Server
const server = new Server(
{
name: 'mcp-server-tmdb',
version: '1.0.0',
},
{
capabilities: {
tools: {},
},
}
);
// Required tools for ChatGPT
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
{
name: 'search',
description: 'Search for movies by title or keywords using TMDB',
inputSchema: {
type: 'object',
properties: {
query: {
type: 'string',
description: 'Search query for movies',
},
},
required: ['query'],
},
},
{
name: 'fetch',
description: 'Fetch detailed information about a specific movie by ID',
inputSchema: {
type: 'object',
properties: {
movieId: {
type: 'string',
description: 'TMDB movie ID to fetch details for',
},
},
required: ['movieId'],
},
},
{
name: 'get_recommendations',
description: 'Get movie recommendations based on a movie ID',
inputSchema: {
type: 'object',
properties: {
movieId: {
type: 'string',
description: 'TMDB movie ID',
},
},
required: ['movieId'],
},
},
{
name: 'get_trending',
description: 'Get trending movies for a specified time window',
inputSchema: {
type: 'object',
properties: {
timeWindow: {
type: 'string',
description: 'Time window: "day" or "week"',
enum: ['day', 'week'],
},
},
required: ['timeWindow'],
},
},
],
};
});
server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
const apiKey = process.env.TMDB_API_KEY;
if (!apiKey) {
throw new Error('TMDB_API_KEY environment variable is required');
}
try {
switch (name) {
case 'search': {
const response = await fetch(
`https://api.themoviedb.org/3/search/movie?api_key=${apiKey}&query=${encodeURIComponent(args.query)}`
);
const data = await response.json();
return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
}
case 'fetch': {
const response = await fetch(
`https://api.themoviedb.org/3/movie/${args.movieId}?api_key=${apiKey}`
);
const data = await response.json();
return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
}
case 'get_recommendations': {
const response = await fetch(
`https://api.themoviedb.org/3/movie/${args.movieId}/recommendations?api_key=${apiKey}`
);
const data = await response.json();
return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
}
case 'get_trending': {
const response = await fetch(
`https://api.themoviedb.org/3/trending/movie/${args.timeWindow}?api_key=${apiKey}`
);
const data = await response.json();
return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
}
default:
throw new Error(`Unknown tool: ${name}`);
}
} catch (error) {
throw new Error(`Tool execution failed: ${error.message}`);
}
});
// Handle POST requests for client-to-server communication
app.post('/mcp', async (req, res) => {
const sessionId = req.headers['mcp-session-id'] || randomUUID();
let transport;
if (transports[sessionId]) {
transport = transports[sessionId];
} else {
transport = new StreamableHTTPServerTransport(server);
transports[sessionId] = transport;
}
// Set session ID in response header
res.setHeader('Mcp-Session-Id', sessionId);
await transport.handlePostRequest(req, res);
});
// Handle GET requests for server-to-client streaming
app.get('/mcp', async (req, res) => {
const sessionId = req.headers['mcp-session-id'] || randomUUID();
let transport;
if (transports[sessionId]) {
transport = transports[sessionId];
} else {
transport = new StreamableHTTPServerTransport(server);
transports[sessionId] = transport;
}
// Set session ID in response header
res.setHeader('Mcp-Session-Id', sessionId);
await transport.handleGetRequest(req, res);
});
// Status endpoint
app.get('/', (req, res) => {
res.json({
name: 'TMDB MCP Server',
version: '1.0.0',
status: 'running',
transport: 'streamable-http',
endpoints: {
mcp: '/mcp'
}
});
});
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
console.log(`TMDB MCP Server running on port ${PORT}`);
console.log(`MCP endpoint: http://localhost:${PORT}/mcp`);
});
```
--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
```typescript
#!/usr/bin/env node
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import fetch from 'node-fetch';
import {
CallToolRequestSchema,
ListResourcesRequestSchema,
ListToolsRequestSchema,
ReadResourceRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
// Type definitions
interface Movie {
id: number;
title: string;
release_date: string;
vote_average: number;
overview: string;
poster_path?: string;
genres?: Array<{ id: number; name: string }>;
}
interface TMDBResponse {
page: number;
results: Movie[];
total_pages: number;
}
interface MovieDetails extends Movie {
credits?: {
cast: Array<{
name: string;
character: string;
}>;
crew: Array<{
name: string;
job: string;
}>;
};
reviews?: {
results: Array<{
author: string;
content: string;
rating?: number;
}>;
};
}
const TMDB_API_KEY = process.env.TMDB_API_KEY;
const TMDB_BASE_URL = "https://api.themoviedb.org/3";
const server = new Server(
{
name: "example-servers/tmdb",
version: "0.1.0",
},
{
capabilities: {
resources: {},
tools: {},
},
}
);
async function fetchFromTMDB<T>(endpoint: string, params: Record<string, string> = {}): Promise<T> {
const url = new URL(`${TMDB_BASE_URL}${endpoint}`);
url.searchParams.append("api_key", TMDB_API_KEY!);
for (const [key, value] of Object.entries(params)) {
url.searchParams.append(key, value);
}
const response = await fetch(url.toString());
if (!response.ok) {
throw new Error(`TMDB API error: ${response.statusText}`);
}
return response.json() as Promise<T>;
}
async function getMovieDetails(movieId: string): Promise<MovieDetails> {
return fetchFromTMDB<MovieDetails>(`/movie/${movieId}`, { append_to_response: "credits,reviews" });
}
server.setRequestHandler(ListResourcesRequestSchema, async (request) => {
const params: Record<string, string> = {
page: request.params?.cursor || "1",
};
const data = await fetchFromTMDB<TMDBResponse>("/movie/popular", params);
return {
resources: data.results.map((movie) => ({
uri: `tmdb:///movie/${movie.id}`,
mimeType: "application/json",
name: `${movie.title} (${movie.release_date.split("-")[0]})`,
})),
nextCursor: data.page < data.total_pages ? String(data.page + 1) : undefined,
};
});
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
const movieId = request.params.uri.replace("tmdb:///movie/", "");
const movie = await getMovieDetails(movieId);
const movieInfo = {
title: movie.title,
releaseDate: movie.release_date,
rating: movie.vote_average,
overview: movie.overview,
genres: movie.genres?.map(g => g.name).join(", "),
posterUrl: movie.poster_path ?
`https://image.tmdb.org/t/p/w500${movie.poster_path}` :
"No poster available",
cast: movie.credits?.cast?.slice(0, 5).map(actor => `${actor.name} as ${actor.character}`),
director: movie.credits?.crew?.find(person => person.job === "Director")?.name,
reviews: movie.reviews?.results?.slice(0, 3).map(review => ({
author: review.author,
content: review.content,
rating: review.rating
}))
};
return {
contents: [
{
uri: request.params.uri,
mimeType: "application/json",
text: JSON.stringify(movieInfo, null, 2),
},
],
};
});
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
{
name: "search_movies",
description: "Search for movies by title or keywords",
inputSchema: {
type: "object",
properties: {
query: {
type: "string",
description: "Search query for movie titles",
},
},
required: ["query"],
},
},
{
name: "get_recommendations",
description: "Get movie recommendations based on a movie ID",
inputSchema: {
type: "object",
properties: {
movieId: {
type: "string",
description: "TMDB movie ID to get recommendations for",
},
},
required: ["movieId"],
},
},
{
name: "get_trending",
description: "Get trending movies for a time window",
inputSchema: {
type: "object",
properties: {
timeWindow: {
type: "string",
enum: ["day", "week"],
description: "Time window for trending movies",
},
},
required: ["timeWindow"],
},
},
],
};
});
server.setRequestHandler(CallToolRequestSchema, async (request) => {
try {
switch (request.params.name) {
case "search_movies": {
const query = request.params.arguments?.query as string;
const data = await fetchFromTMDB<TMDBResponse>("/search/movie", { query });
const results = data.results
.map((movie) =>
`${movie.title} (${movie.release_date?.split("-")[0]}) - ID: ${movie.id}\n` +
`Rating: ${movie.vote_average}/10\n` +
`Overview: ${movie.overview}\n`
)
.join("\n---\n");
return {
content: [
{
type: "text",
text: `Found ${data.results.length} movies:\n\n${results}`,
},
],
isError: false,
};
}
case "get_recommendations": {
const movieId = request.params.arguments?.movieId as string;
const data = await fetchFromTMDB<TMDBResponse>(`/movie/${movieId}/recommendations`);
const recommendations = data.results
.slice(0, 5)
.map((movie) =>
`${movie.title} (${movie.release_date?.split("-")[0]})\n` +
`Rating: ${movie.vote_average}/10\n` +
`Overview: ${movie.overview}\n`
)
.join("\n---\n");
return {
content: [
{
type: "text",
text: `Top 5 recommendations:\n\n${recommendations}`,
},
],
isError: false,
};
}
case "get_trending": {
const timeWindow = request.params.arguments?.timeWindow as string;
const data = await fetchFromTMDB<TMDBResponse>(`/trending/movie/${timeWindow}`);
const trending = data.results
.slice(0, 10)
.map((movie) =>
`${movie.title} (${movie.release_date?.split("-")[0]})\n` +
`Rating: ${movie.vote_average}/10\n` +
`Overview: ${movie.overview}\n`
)
.join("\n---\n");
return {
content: [
{
type: "text",
text: `Trending movies for the ${timeWindow}:\n\n${trending}`,
},
],
isError: false,
};
}
default:
throw new Error("Tool not found");
}
} catch (error) {
return {
content: [
{
type: "text",
text: `Error: ${error instanceof Error ? error.message : 'Unknown error occurred'}`,
},
],
isError: true,
};
}
});
// Start the server
if (!TMDB_API_KEY) {
console.error("TMDB_API_KEY environment variable is required");
process.exit(1);
}
const transport = new StdioServerTransport();
server.connect(transport).catch((error) => {
console.error("Server connection error:", error);
process.exit(1);
});
```