-tmdb-mcp-服务器

Name: -tmdb-mcp-服务器
Author: SergioDeIscarValera

作者：SergioDeIscarValera2 星标更新：2025-10-28

安装使用来源：spider==github.com

项目介绍

TMDB MCP Server

这是一个无缝集成The Movie Database (TMDB) API与OpenAI Apps SDK的模型上下文协议（MCP）服务器。该项目使AI代理（如ChatGPT或Claude中的那些）能够调用电影相关查询工具，渲染交互式视觉组件（例如，轮播、详情卡片和预告片缩略图），同时遵循OpenAI的设计指南以实现原生、对话式的体验。

此服务器专为实验MCP的开发者设计，支持AI驱动的电影发现、推荐和媒体浏览。它被设计成模块化、可扩展且生产就绪，重点在于清晰的架构和复用性。

注意：此项目需要一个TMDB API密钥（提供免费层级）。在.env中设置为TMDB_API_KEY=your_key_here。

目的

本项目的中心目标是将TMDB丰富的电影数据与MCP连接起来，允许AI模型：

查询和发现：搜索电影、演员、类型和趋势。
可视化结果：渲染UI组件，如搜索结果、详情视图和可点击的预告片缩略图的轮播。
链式操作：工具返回结构化数据（如JSON ID），供AI进行链式调用（如搜索→获取详情→显示预告片）。
增强AI工作流：非视觉工具提供原始数据用于推理，而视觉工具则创建引人入胜的内联体验于AI聊天中。

该设置展示了如何通过遵循OpenAI的设计指南，MCP可以扩展AI代理与外部API的无缝集成——对话式、简单且易于访问。

已使用MCPJam Inspector（类似于Postman的MCP服务器调试工具）进行本地调试、工具执行和LLM模拟。MCPJam支持STDIO/SSE/HTTP传输和多模型测试（如Claude、GPT）。

功能

核心工具：
- getMovieIdByTitle：从标题获取电影ID（文本输出用于链式调用）。
- getMovieGenres：列出可用类型供过滤（JSON）。
- searchActorsIds：搜索演员并返回ID/姓名（JSON）。
- getReviews：获取指定语言的电影评论（JSON）。
视觉工具（带UI组件）：
- getMovieCarousel：搜索电影并渲染响应式轮播。
- getMovieDetails：展示详细的电影信息（海报、演员阵容、类型）。
- getRecommendations：相似电影的轮播。
- getMoviesByGenre：基于类型的电影发现轮播（先使用getMovieGenres）。
- getMoviesByActor：演员作品集轮播（先使用searchActorsIds）。
- getTrending：热门电影轮播（每日/每周）。
getUpcoming：即将上映的电影轮播。
getTrailer：可点击的预告片缩略图（在新标签页中打开YouTube）。
设计合规性：所有UI使用自定义的OpenAI启发的CSS系统，包括浅色/深色模式、间距比例和无障碍性（WCAG 2.1）。
测试与调试：兼容MCPJam Inspector进行视觉工具测试和LLM模拟。

技术栈

类别	技术
框架	xMCP（MCP服务器搭建，自动注册工具/资源）
API集成	TMDB API（v3，带有Zod验证）
UI渲染	MCP UI（`@mcp-ui/server`用于rawHtml资源）
设计系统	自定义OpenAI Apps SDK CSS（颜色、间距、字体、阴影变量）
验证	Zod（输入/输出模式）
环境	TypeScript, Node.js 20+, HTTP传输（可配置为STDIO）
测试	MCPJam Inspector（本地MCP调试，LLM游乐场）
部署	兼容Vercel/Next.js（通过xMCP适配器）

项目结构

.
├── package.json          # 依赖项和脚本
├── package-lock.json     # 锁定文件
├── README.md            # 您在这里
├── src/
│   ├── prompts/         # MCP提示（例如，review-code.ts）
│   ├── resources/       # UI小部件（rawHtml组件）
│   │   └── (movies)/
│   │       ├── [query]/     # 动态：carousel.ts（可用于搜索）
│   │       └── [movieId]/  # 动态：details.ts, trailer.ts
│   ├── services/        # API逻辑（tmdbService.ts，带有Zod模式）
│   ├── styles/          # 设计系统（openaiDesing.ts）
│   └── tools/           # MCP工具（端点，例如getMovieCarousel.ts）
├── tsconfig.json        # TypeScript配置
├── xmcp.config.ts       # xMCP配置（HTTP传输，路径）
└── xmcp-env.d.ts        # 类型声明

快速开始

前提条件

Node.js 20+。
TMDB API密钥（设置在.env中）。

安装

克隆仓库：

git clone https://github.com/SergioDeIscarValera/tmdb-mcp-server.git
cd tmdb-mcp-server

安装依赖项：
```
npm install
```
设置.env：
```
TMDB_API_KEY=your_tmdb_api_key_here
```
开发模式运行：
```
npm run dev
```
- 服务器启动于http://localhost:3001/mcp。

使用MCPJam Inspector测试

安装MCPJam Inspector：
```
npx @mcpjam/inspector@beta
```
- 在浏览器中打开进行视觉测试。
连接您的服务器：
- 添加HTTP服务器：http://localhost:3001/mcp。
- 测试工具（如getMovieCarousel）、资源和提示。
- 使用LLM游乐场模拟AI调用。

使用示例

通过mcp.json连接到Cursor/Claude Desktop：

{
  "mcpServers": {
    "tmdb-mcp-server": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

提示："显示《盗梦空间》电影的轮播。"

AI调用getMovieCarousel → 渲染视觉轮播。

API端点及工具

所有工具均通过xMCP自动注册。关键示例：

工具	描述	输入	输出
`getMovieCarousel`	搜索电影 → 轮播UI	`query: string`	视觉轮播
`getMovieDetails`	电影详情 → 卡片UI	`movieId: number`	视觉详情
`getRecommendations`	相似电影 → 轮播	`movieId: number`	视觉轮播
`getMovieIdByTitle`	标题 → ID	`title: string`	文本ID（例如，“27205”）
`getReviews`	评论 → JSON	`movieId: number, language: string`	文本JSON
`getTrailer`	预告片缩略图 → 可点击UI	`movieId: number`	视觉缩略图（打开YouTube）

完整列表在src/tools/中。

部署

Vercel：使用xMCP的Next.js适配器（npx init-xmcp@latest与Next.js）。
构建：npm run build → 部署dist/http.js。
环境变量：在生产环境中设置TMDB_API_KEY。

许可证

此项目是开源的，免费使用、修改和分发，没有任何限制。欢迎复制、改编或在此基础上构建任何用途。提及或向原作者Sergio de Iscar Valera致谢是受欢迎的，但不是必须的。

致谢

作者：Sergio de Iscar Valera
技术：xMCP, TMDB API, OpenAI Apps SDK, MCP UI, Zod, MCPJam Inspector
灵感来源：OpenAI的MCP设计指南和TMDB的开发者社区

欢迎通过GitHub贡献、报告问题或提出改进建议！🚀