AI导哈

电影数据库协议服务器

一个提供对电影数据库(TMDB) API访问的模型上下文协议(MCP)服务器，支持电影搜索、详细信息获取、趋势发现等功能，适用于本地和远程客户端集成。

  • by stormino
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 stormino/tmdb-mcp-server

使用说明

TMDB MCP 服务器

一个模型上下文协议（MCP）服务器，为Claude和其他MCP客户端提供访问电影数据库（TMDB）API的权限。

特点/特性

  • 按电影标题搜索
  • 获取详细的电影信息
  • 发现热门电影
  • 搜索演员和导演
  • 获取个人详细信息及作品列表
  • 获取电影推荐
  • 使用筛选器进行高级电影发现

双模式支持

这台服务器有两种工作模式：

  • **本地（标准输入输出）**适用于 Claude Desktop 和本地 MCP 客户端
  • **远程（HTTP）**对于claude.ai网站和远程集成

先决条件

安装

# Clone the repository
git clone https://github.com/stormino/tmdb-mcp-server.git
cd tmdb-mcp-server

# Install dependencies
go mod tidy

# Build the server
go build -o tmdb-mcp-server

配置

将您的TMDB API密钥设置为环境变量：

export TMDB_API_KEY=your_api_key_here

使用方法

本地模式（Claude 桌面版）

  1. 构建服务器（参见上方的安装说明）

  2. 通过编辑配置文件来配置Claude Desktop：

    • macOS（苹果电脑操作系统）: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Linux： ~/.config/Claude/claude_desktop_config.json
    • Windows： %APPDATA%\Claude\claude_desktop_config.json

  3. 添加此配置：

{
  "mcpServers": {
    "tmdb": {
      "command": "/absolute/path/to/tmdb-mcp-server",
      "args": ["--mode", "stdio"],
      "env": {
        "TMDB_API_KEY": "your_api_key_here"
      }
    }
  }
}

  1. 重启Claude桌面版

  2. 向克劳德询问诸如：

    • “搜索克里斯托弗·诺兰执导的电影”
    • “本周热门电影有哪些？”
    • “给我讲讲《盗梦空间》这部电影的详细情况。”

远程模式（HTTP服务器）

以HTTP模式运行服务器：

./tmdb-mcp-server --mode http --port 8080
# Or use make:
make run-http

在本地测试HTTP模式

选项1：MCP检查器（推荐）

# Terminal 1: Start server
make run-http

# Terminal 2: Open MCP Inspector
make inspector
# Or: npx @modelcontextprotocol/inspector

然后连接到 http://localhost:8080 在 http://localhost:5173 的检查器用户界面中

选项2：cURL

# Test with curl (in another terminal)
make test-http

选项3：从claude.ai进行连接

  1. 暴露你的本地服务器（例如，使用ngrok： ngrok http 8080）
  2. 访问 claude.ai → 设置 → 连接器
  3. 点击“添加自定义连接器”
  4. 输入您的服务器URL： https://your-ngrok-url.ngrok.io

如需详细的测试说明，请参阅 TEST_HTTP_MODE.md 翻译为中文是：“测试HTTP模式.md”

命令行选项

./tmdb-mcp-server [options]

Options:
  --mode string
        Transport mode: stdio or http (default "stdio")
        Can also be set via MCP_MODE environment variable
  
  --port string
        HTTP port, only used in http mode (default "8080")
        Can also be set via HTTP_PORT environment variable

可用工具

工具名称 描述 输入
search_movies 按标题搜索电影 查询语句，年份（可选）
get_movie_details 获取详细电影信息 电影ID
get_trending 获取热门电影 时间窗口（天/周）
search_person 搜索人员 查询
get_person_details 获取人物详情和作品列表 person_id
get_recommendations 获取电影推荐 电影ID，限制数量
discover_movies 带筛选功能的高级电影搜索 电影类型、年份、最低评分等。

示例查询

  • “查找与《星际穿越》相似的电影”
  • “《黑暗骑士》是由谁执导的，他们还有哪些其他电影？”
  • “2023年评分最高的科幻电影有哪些？”
  • “给我看看本周热门电影”
  • “搜索汤姆·汉克斯并列出他最受欢迎的电影”

接下来，将进行一系列非常复杂的提示测试，以探索MCP服务器的功能。

多功能工具链提示符

  • 深度电影制作人分析：

    分析克里斯托弗·诺兰的职业轨迹：查找他的所有电影，追踪其平均评分随时间的变化，找出他最常合作的伙伴（出演过3部及以上其电影的演员），并制作一份Markdown报告，展示他探索过的类型以及票房表现的增长情况。同时，提供一些类似导演的推荐，以供我进一步探索

  • 特许经营深度解析：

    “我想一口气看完漫威电影宇宙。请帮我搜索所有漫威电影宇宙的电影，按上映日期排序，告诉我哪些评分最高，估算一下看完所有电影的总时长，然后对于评分最高的前5部电影，给我推荐一些类似的非漫威电影。”

  • 演员职业生涯对比：

    “比较莱昂纳多·迪卡普里奥和汤姆·汉克斯的职业生涯：搜索这两位演员，获取他们的完整电影作品列表，计算他们电影的平均评分，找出他们表现最出色的十年，找出他们共同出演过的电影，并根据评分和受欢迎程度，为我推荐每位演员的3部绝对不容错过的电影。”

热门趋势与发现

  • 智能趋势分析：

    “本周热门电影有哪些？对于每部电影，请告诉我：它为何成为热门（分析上映日期、评分、类型），推荐类似电影，并根据评分高于7.5分且片长不超过2.5小时的标准，为我列出应优先观看的热门电影排名。”

  • 类型探索挑战：

    “我想探索一些我从未听说过的科幻电影。使用‘发现’功能来查找2020年至2024年间评分在7.0以上的、且不在前20名热门之列的科幻电影。对于前5个结果，获取详细信息，并告诉我每部电影的独特之处。然后寻找类似的隐藏佳作。”

  • 十年时光机：

    “带我游览一下90年代：找出那个十年中评分最高的动作电影，获取前五名的详细信息，找出哪些演员出演了多部电影，并根据上映日期和主题关联性，创建一个包含观看顺序的‘90年代动作电影初学者套装’。”

富有创意且复杂

  • 完美的电影之夜策划者：

    “我要为4个人举办一个电影之夜。我们都很喜欢《盗梦空间》、《肖申克的救赎》和《寄生虫》。请帮我找至少2部与这些电影相似的作品，筛选时长不超过150分钟且评分在8.0以上的电影，检查是否有共同的导演或演员，并制作一个包含5部最佳选项的排名列表，同时解释每部电影为何适合。”

  • 导演的愿景演变：

    追踪昆汀·塔伦蒂诺作为导演的演变历程：按时间顺序找出他的所有电影，分析他的评分随时间的变化，找出他电影中反复出现的演员，获取他评分最高和最低的电影的详细信息，并制作一份“三幕式昆汀指南”，展示他早期、中期和近期的代表作

  • 终极大盗电影数据库

    “为我打造终极的越狱电影收藏：找出所有评分超过7.0的越狱/犯罪电影，按十年为单位进行分类，找出哪些演员在越狱电影中出现频率最高，推荐一些我可能遗漏的冷门佳作，并创建一个从‘必备’到‘隐藏瑰宝’的分级观影列表。”

数据分析与洞察

  • 评分模式分析：

    “找出过去20年所有获得最佳影片奖的奥斯卡获奖作品，获取它们在TMDB（The Movie Database）上的评分，并告诉我：奥斯卡获奖作品在观众评分上是否真的更高？哪部获奖作品评分最高？请推荐与前三名相似的作品，并找出在类型或导演方面是否存在任何规律。”

  • 流媒体策略：

    “我有一个空闲的周末。请搜索本周的热门电影，获取所有电影的详细信息，计算出哪5-6部电影的组合能给我带来最多的多样性（不同类型）、最高的平均评分，并且总时长不超过12小时。制定一个最佳观影计划。”

  • 特许经营疲劳度检查：

    “电影系列作品的质量是否随着时间推移而变差？请选出3个主要系列（搜索星球大战、速度与激情和碟中谍系列电影），追踪从第一部到最新电影的评分变化，找出每个系列中质量最高的电影，并告诉我是否有证据表明质量在下降。”

压力测试/炫耀提示

  • TMDB大旅行

    “让我们来做个终极测试：（1）找出今天流行什么，（2）获取排名第一的热门电影的详细信息，（3）找到这部电影的导演，（4）获取他们的完整作品列表，（5）基于他们评分最高的电影，找出相关推荐，（6）对于这些推荐，找出是否有共同的演员，（7）创建一个包含评分、类型以及我为什么应该观看每一部的全面观影指南。”

  • 电影宇宙构建者：

    “我想打造一场属于自己的主题电影马拉松。搜索剧情中包含‘时间旅行’的电影，获取评分最高的前十部电影的详细信息，找出哪些演员出演过多部时间旅行电影，为每部电影寻找可能也涉及时间/现实操控元素的推荐影片，并策划一场‘时间电影节’，包括观影顺序、简要介绍以及电影之间有趣联系的趣闻。”

  • “六度挑战”：

    “从凯文·贝肯开始。获取他的详细信息和排名前十的电影。从中挑选三部电影，查找它们的完整演员阵容详情。对于这些演员，查找他们其他评分最高的电影。创建一张连接图，展示不同演员和电影是如何相互关联的，并通过这个网络推荐一条观影路径。”

创意输出格式

  • 电影推荐新闻简报：

    创建一份电影新闻简报：查找本周热门电影，发掘隐藏的瑰宝（评分高但人气低），获取一部经典电影推荐（2000年前的，评分>8），并以Markdown格式组织所有内容，包括各部分、评分、表情符号以及针对每部电影为何值得观看的个性化评论

  • 电影节节目策划人：

    “我正在策划一个迷你电影节。主题是‘梦想与现实’。寻找不同年代中符合这一主题且评分较高的电影，获取详细信息，发现导演之间的关联，并策划一个电影节节目，包括开幕影片、核心影片和闭幕影片，同时附上每部影片为何符合主题的描述。”

  • 算法电影评论家：

    “扮演电影评论AI：搜索本周热门电影，获取每部电影的详细信息，分析它们的评分与预算（如数据可用），识别当前表现良好的电影类型，并根据数据撰写一篇关于当今电影界成功要素的趋势分析文章。”

发展

建筑

此服务器实现了模型上下文协议（MCP），具体包括：

  • 客户端-主机-服务器架构 基于JSON-RPC 2.0构建
  • 双运输模式相同的代码库既可在本地（stdio）运行，也可在远程（HTTP+SSE）运行
  • 7种已全面实施的工具 用于电影发现和信息检索

技术栈

  • 语言Go 1.25及以上版本
  • MCP SDK（MCP软件开发工具包）： github.com/modelcontextprotocol/go-sdk v1.0.0（版本1.0.0）
  • TMDB库： github.com/cyruzin/golang-tmdb v1.8.2

建筑

# Install dependencies
go mod download
go mod tidy

# Build
go build -o tmdb-mcp-server

# Or use Makefile
make build

测试

# Test stdio mode
./tmdb-mcp-server --mode stdio

# Test HTTP mode
./tmdb-mcp-server --mode http --port 8080

# Run tests (when implemented)
go test -v ./...

# Or use Makefile
make test

代码质量

# Format code
go fmt ./...
# Or: make fmt

# Run linter (requires golangci-lint)
make lint

Docker 支持

Dockerfile 包含两个构建目标： stdio （默认）和 http预构建的镜像会自动发布到 GitHub 容器注册表。

使用预构建的镜像

# Pull and run stdio mode (default)
docker run -e TMDB_API_KEY=your_key ghcr.io/stormino/tmdb-mcp-server:latest

# Pull and run HTTP mode
docker run -p 8080:8080 -e TMDB_API_KEY=your_key ghcr.io/stormino/tmdb-mcp-server:http

# Use a specific version
docker run -e TMDB_API_KEY=your_key ghcr.io/stormino/tmdb-mcp-server:v1.0.0
docker run -p 8080:8080 -e TMDB_API_KEY=your_key ghcr.io/stormino/tmdb-mcp-server:v1.0.0-http

可用的镜像标签：

  • latest / stdio - 来自主分支的最新stdio模式构建版本
  • http - 最新从主分支构建的HTTP模式
  • v* - 标准I/O模式版本标签（例如。， v1.0.0， v1.1.0）
  • v*-http - HTTP模式的版本标签（例如。， v1.0.0-http）

从源代码构建

# Build default stdio image
docker build -t tmdb-mcp-server .

# Build HTTP mode image
docker build --target http -t tmdb-mcp-server:http .

# Or use make:
make docker-build

运行中的容器

标准输入输出模式（默认）：

docker run -e TMDB_API_KEY=your_key tmdb-mcp-server

HTTP 模式（使用 http 目标）：

docker run -p 8080:8080 -e TMDB_API_KEY=your_key tmdb-mcp-server:http

HTTP 模式（覆盖标准 I/O 图像）：

docker run -p 8080:8080 -e TMDB_API_KEY=your_key tmdb-mcp-server --mode http

自定义端口（HTTP 图像）：

# Using HTTP_PORT environment variable
docker run -p 3000:3000 -e TMDB_API_KEY=your_key -e HTTP_PORT=3000 tmdb-mcp-server:http

# Or using command-line flag
docker run -p 3000:3000 -e TMDB_API_KEY=your_key tmdb-mcp-server:http --port 3000

故障排除

TMDB_API_KEY 环境变量是必需的

确保你已设置TMDB_API_KEY环境变量或在你的Claude Desktop配置中包含了它。

Claude 桌面版无法连接到服务器

  1. 检查可执行文件的路径是否为绝对路径
  2. 验证TMDB_API_KEY是否有效
  3. 检查Claude Desktop的日志以查找错误
  4. 尝试手动运行服务器进行测试： ./tmdb-mcp-server --mode stdio

做出贡献

欢迎贡献！改进方向：

优先级增强：

  • 单元测试和集成测试
  • API响应的缓存层
  • 速率限制实现
  • 流媒体可用性集成

附加功能：

  • MCP资源（例如。， tmdb://trending/movies/week)
  • MCP 提示（例如，“分析电影评论”）
  • 图像URL构建辅助工具
  • 多语言支持
  • 大型结果集的分页处理
  • HTTP模式的身份验证

需要考虑的问题：

  • 我们应该添加流媒体可用性数据吗？（需要额外的API）
  • 我们应该为结果支持多种语言吗？
  • 除了电影，我们是否应该增加对电视剧的支持？
  • 除了HTTP+SSE之外，我们是否应该实现WebSocket传输？

许可证

MIT 许可证 - 欢迎在您的项目中自由使用！

资源

功劳；贡献

使用以下技术构建：

相关 MCP