# Directory Structure
```
├── .gitignore
├── LICENSE
├── package.json
├── README.md
├── src
│ ├── index.ts
│ └── types
│ └── modelcontextprotocol.d.ts
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
# Dependencies
node_modules/
package-lock.json
# Build output
dist/
# Environment variables
.env
.env.local
.env.*.local
# IDE - VSCode
.vscode/
.idea/
# OS generated files
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db
# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
# TMDB MCP Server
A Model Context Protocol (MCP) server that provides access to The Movie Database (TMDB) API. This server enables AI assistants to search and retrieve movie information through the MCP interface.
## Features
- Search movies by title, year, and other criteria
- Retrieve detailed movie information
- Easy integration with MCP-compatible AI assistants
## Prerequisites
- Node.js >= 18
- TMDB API key (get one from [TMDB](https://www.themoviedb.org/documentation/api))
## Installation
1. Clone the repository:
```bash
git clone https://github.com/rakeshgangwar/tmdb-mcp-server.git
cd tmdb-mcp-server
```
2. Install dependencies:
```bash
npm install
```
3. Build the server:
```bash
npm run build
```
## Configuration
Configure the MCP server in your MCP settings file (typically `cline_mcp_settings.json`):
```json
{
"mcpServers": {
"tmdb": {
"command": "node",
"args": ["/path/to/tmdb-mcp-server/dist/index.js"],
"env": {
"TMDB_API_KEY": "your-api-key-here"
},
"disabled": false,
"autoApprove": []
}
}
}
```
Replace `your-api-key-here` with your TMDB API key and replace `/path/to/` with actual path.
## Available Tools
### search_movies
Search for movies using The Movie Database API.
Parameters:
- `query` (required): Search query string
- `year` (optional): Filter by release year
- `page` (optional): Page number (default: 1)
Example:
```javascript
{
"query": "Inception",
"year": 2010,
"page": 1
}
```
## Development
1. Make your changes in the `src` directory
2. Build the project:
```bash
npm run build
```
3. Test your changes by configuring the MCP server in your settings
## Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -am 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- [TMDB API](https://www.themoviedb.org/documentation/api) for providing the movie database API
- [Model Context Protocol](https://github.com/modelcontextprotocol) for the MCP SDK
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
{
"name": "tmdb-mcp-server",
"version": "1.0.0",
"description": "TMDB MCP Server for accessing The Movie Database API",
"main": "dist/index.js",
"scripts": {
"clean": "rm -rf dist",
"prebuild": "npm run clean",
"build": "tsc",
"postbuild": "chmod +x dist/index.js"
},
"type": "module",
"devDependencies": {
"@types/node": "^16.18.126",
"typescript": "^5.8.2"
},
"dependencies": {
"@modelcontextprotocol/sdk": "1.7.0",
"axios": "^1.8.3"
}
}
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
{
"compilerOptions": {
"target": "es2020",
"module": "es2020",
"lib": ["es2020"],
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"moduleResolution": "node",
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"allowSyntheticDefaultImports": true,
"allowJs": true,
"typeRoots": [
"./node_modules/@types",
"./src/types"
],
"noImplicitAny": false
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}
```
--------------------------------------------------------------------------------
/src/types/modelcontextprotocol.d.ts:
--------------------------------------------------------------------------------
```typescript
declare module '@modelcontextprotocol/sdk' {
export class Server {
constructor(info: { name: string; version: string }, options: { capabilities: { tools: any } });
setRequestHandler(schema: any, handler: Function): void;
connect(transport: any): Promise<void>;
}
export class StdioServerTransport {
constructor();
}
export const CallToolRequestSchema: unique symbol;
export const ListToolsRequestSchema: unique symbol;
export interface CallToolRequest {
params: {
name: string;
arguments?: Record<string, unknown>;
};
}
}
```
--------------------------------------------------------------------------------
/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 {
CallToolRequestSchema,
ErrorCode,
ListToolsRequestSchema,
McpError,
} from '@modelcontextprotocol/sdk/types.js';
import axios from 'axios';
const TMDB_ACCESS_TOKEN = process.env.TMDB_ACCESS_TOKEN;
if (!TMDB_ACCESS_TOKEN) {
throw new Error('TMDB_ACCESS_TOKEN environment variable is required');
}
class TMDBServer {
private server: Server;
private axiosInstance;
constructor() {
this.server = new Server(
{
name: 'tmdb-server',
version: '0.1.0',
},
{
capabilities: {
resources: {},
tools: {},
},
}
);
this.axiosInstance = axios.create({
baseURL: 'https://api.themoviedb.org/3',
headers: {
'Authorization': `Bearer ${TMDB_ACCESS_TOKEN}`,
'accept': 'application/json'
},
});
this.setupToolHandlers();
this.server.onerror = (error) => console.error('[MCP Error]', error);
process.on('SIGINT', async () => {
await this.server.close();
process.exit(0);
});
}
private setupToolHandlers() {
this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
{
name: 'search_movies',
description: 'Search for movies using The Movie Database API',
inputSchema: {
type: 'object',
properties: {
query: {
type: 'string',
description: 'Search query',
},
year: {
type: 'number',
description: 'Filter by release year (optional)',
},
page: {
type: 'number',
description: 'Page number (default: 1)',
},
},
required: ['query'],
},
},
],
}));
this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name !== 'search_movies') {
throw new McpError(
ErrorCode.MethodNotFound,
`Unknown tool: ${request.params.name}`
);
}
const args = request.params.arguments as {
query: string;
year?: number;
page?: number;
};
const { query, year, page = 1 } = args;
try {
const response = await this.axiosInstance.get('/search/movie', {
params: {
query,
year,
page,
},
});
return {
content: [
{
type: 'text',
text: JSON.stringify(response.data, null, 2),
},
],
};
} catch (error) {
if (axios.isAxiosError(error)) {
return {
content: [
{
type: 'text',
text: `TMDB API error: ${
error.response?.data.message ?? error.message
}`,
},
],
isError: true,
};
}
throw error;
}
});
}
async run() {
const transport = new StdioServerTransport();
await this.server.connect(transport);
console.error('TMDB MCP server running on stdio');
}
}
const server = new TMDBServer();
server.run().catch(console.error);
```