Marvel MCP 服务器

功能 • 工具 • 设置 • 配置 MCP 主机

用于 Marvel 开发者 API 的 MCP 服务器，能够与角色和漫画数据进行交互。该项目的主要目标是展示如何使用 MCP 服务器与 API 进行交互。

注意：此 MCP 服务器使用的所有数据均来自 官方 Marvel API，并由 Marvel 拥有。此项目与 Marvel 无任何关联。

🔧 功能

• 列出 Marvel 角色：支持 nameStartsWith、limit、comics、series 等过滤器。
• 通过 ID 获取 Marvel 角色：使用 characterId 获取任何角色的详细信息。
• 获取角色的漫画：获取包含特定角色的漫画列表，并支持 format、dateRange 等多种过滤器。
• 基于工具的 MCP 集成：将此服务器注册到 Model Context Protocol (MCP) 工具（如 VS Code、Claude 等）。
• 环境配置：使用 .env 文件管理 MARVEL_PUBLIC_KEY、MARVEL_PRIVATE_KEY 和 MARVEL_API_BASE 等环境变量。

🧰 工具

1. get_characters 🔍🦸‍♂️

• 描述：获取带有可选过滤器的 Marvel 角色。
• 输入：
  • name (可选字符串)：完整角色名称。
  • nameStartsWith (可选字符串)：以指定字符串开头的角色名称。
  • modifiedSince (可选字符串)：ISO 8601 日期字符串，用于筛选自该日期以来修改的角色。
  • comics, series, events, stories (可选字符串)：逗号分隔的相关实体 ID 列表。
  • orderBy (可选字符串)：按指定字段排序结果，例如 name 或 -modified。
  • limit (可选数字)：返回的最大结果数量（1-100）。
  • offset (可选数字)：用于分页的跳过结果数量。
• 返回：匹配角色的 JSON 响应。详情见 src/schemas.ts 中的 CharacterDataWrapperSchema。

2. get_character_by_id 🆔🧑‍🎤

• 描述：通过其唯一 ID 获取 Marvel 角色。
• 输入：
  • characterId (数字)：角色的唯一 ID。
• 返回：角色详细信息的 JSON 响应。详情见 src/schemas.ts 中的 CharacterDataWrapperSchema。

3. get_comics_for_character 📚🎭

• 描述: 获取包含特定角色的漫画，可选过滤条件。
• 输入:
  • characterId (数字): 角色的唯一ID。
  • 可选过滤器:
    • format, formatType (字符串): 按漫画格式过滤（例如：comic, hardcover）。
    • noVariants, hasDigitalIssue (布尔值): 排除变体或仅包括数字版的标志。
    • dateDescriptor (字符串): 预定义的日期范围，如 thisWeek, nextWeek。
    • dateRange (字符串): 自定义日期范围，格式为 YYYY-MM-DD,YYYY-MM-DD。
    • title, titleStartsWith (字符串): 按标题或标题前缀过滤。
    • startYear, issueNumber, digitalId (数字): 数字过滤器。
    • diamondCode, upc, isbn, ean, issn (字符串): 标识符过滤器。
    • creators, series, events, stories, sharedAppearances, collaborators (字符串): 逗号分隔的相关实体ID列表。
    • orderBy (字符串): 结果排序依据的字段，例如 title 或 -modified。
    • limit, offset (数字): 分页选项。
• 返回: 包含指定角色的漫画的JSON响应。详情请参阅 src/schemas.ts 中的 ComicDataWrapperSchema。

4. get_comics 📖🕵️‍♂️

• 描述: 获取带有可选过滤器的漫威漫画列表。
• 输入:
  • format (可选字符串): 按期号格式过滤（例如，comic, digital comic, hardcover）。
  • formatType (可选字符串): 按期号格式类型过滤 (comic 或 collection)。
  • noVariants (可选布尔值): 从结果集中排除变体（如替代封面、二次印刷、导演剪辑版等）。
  • dateDescriptor (可选字符串): 返回预定义日期范围内的漫画 (lastWeek, thisWeek, nextWeek, thisMonth)。
  • dateRange (可选字符串): 返回自定义日期范围内的漫画。日期必须以 YYYY-MM-DD,YYYY-MM-DD 格式指定。
  • title (可选字符串): 仅返回标题与输入匹配的系列中的期号。
  • titleStartsWith (可选字符串): 仅返回标题以输入开头的系列中的期号。
  • startYear (可选数字): 仅返回起始年份与输入匹配的系列中的期号。
  • issueNumber (可选数字): 仅返回期号与输入匹配的系列中的期号。
  • diamondCode, digitalId, upc, isbn, ean, issn (可选字符串): 按各种标识符过滤。
  • hasDigitalIssue (可选布尔值): 仅包括可以数字形式获取的结果。
  • modifiedSince (可选字符串): 仅返回自指定日期以来被修改过的漫画（ISO 8601 格式）。
  • creators, characters, series, events, stories, sharedAppearances, collaborators (可选字符串): 用逗号分隔的相关实体ID列表进行过滤。
  • orderBy (可选字符串): 按字段或多个字段对结果集排序。在值前加 "-" 表示降序排列（例如，title, -modified）。
  • limit (可选数字): 将结果集限制为指定数量的资源（默认: 20, 最大: 100）。
  • offset (可选数字): 在结果集中跳过指定数量的资源。
• 返回: 匹配漫画的JSON响应。详情见 src/schemas.ts 中的 ComicDataWrapperSchema。

5. get_comic_by_id 🆔📘

• 描述: 通过唯一ID获取单个漫威漫画。
• 输入:
  • comicId (数字): 漫画的唯一ID。
• 返回: 漫画详情的JSON响应。详情见 src/schemas.ts 中的 ComicDataWrapperSchema。

6. get_characters_for_comic 🦸‍♀️📖

• 描述: 获取特定漫画中出现的 Marvel 角色。
• 输入:
  • comicId (数字): 漫画的唯一 ID。
  • 可选过滤器:
    • name (可选字符串): 按全名过滤角色。
    • nameStartsWith (可选字符串): 按名称开头的指定字符串过滤角色。
    • modifiedSince (可选字符串): ISO 8601 日期字符串，用于过滤自该日期以来修改的角色。
    • series, events, stories (可选字符串): 逗号分隔的相关实体 ID 列表，用于过滤。
    • orderBy (可选字符串): 用于排序结果的字段，例如 name 或 -modified。
    • limit (可选数字): 返回的最大结果数（1-100）。
    • offset (可选数字): 用于分页的跳过结果数量。
• 返回: 包含在指定漫画中出现的角色的 JSON 响应。详情请参见 src/schemas.ts 中的 CharacterDataWrapperSchema。

🛠️ 设置

注册一个 Marvel Developer API 账户并获取您的公共和私有 API 密钥。

如果您想直接在 MCP 主机上运行，请跳转到 与 Claude Desktop 一起使用 或 与 GitHub Copilot 一起使用 部分。

使用 MCP Inspector 本地运行服务器

如果您希望本地运行 MCP Inspector 来测试服务器，请按照以下步骤操作：

1. 克隆此仓库：

   git clone https://github.com/DanWahlin/marvel-mcp-server
   

2. 将 .env.template 重命名为 .env。

3. 在 .env 文件中添加您的 Marvel API 公共和私有密钥。

   MARVEL_PUBLIC_KEY=YOUR_PUBLIC_KEY
   MARVEL_PRIVATE_KEY=YOUR_PRIVATE_KEY
   MARVEL_API_BASE=https://gateway.marvel.com/v1/public
   

4. 安装所需的依赖项并构建项目。

   npm install
   npm run build
   

5. （可选）要使用 MCP Inspector 测试服务器，请运行以下命令：

   # 启动 MCP Inspector
   npx @modelcontextprotocol/inspector node build/index.js
   

   在浏览器中访问控制台中显示的 MCP Inspector URL。将 Arguments 更改为 dist/index.js 并选择 Connect。选择 List Tools 查看可用工具。

配置 MCP 主机

与 Claude Desktop 一起使用

将以下内容添加到您的 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "marvel-mcp": {
      "type": "stdio",
      "command": "npx",
      // "command": "node",
      "args": [
        "-y",
        "@codewithdan/marvel-mcp"
        // "/PATH/TO/marvel-mcp/dist/index.js"
      ],
      "env": {
        "MARVEL_PUBLIC_KEY": "YOUR_PUBLIC_KEY",
        "MARVEL_PRIVATE_KEY": "YOUR_PRIVATE_KEY",
        "MARVEL_API_BASE": "https://gateway.marvel.com/v1/public"
      }
    }
  }
}

通过 Smithery 安装

要通过 Smithery 自动安装 Marvel MCP Server for Claude Desktop：

npx -y @smithery/cli install @DanWahlin/marvel-mcp --client claude

与 GitHub Copilot (VS Code Insiders) 一起使用

注意: 如果您已经通过 Claude Desktop 启用了 MCP 服务器，在 VS Code 设置中添加 chat.mcp.discovery.enabled: true，它将发现现有的 MCP 服务器列表。

如果要将 MCP 服务器与特定仓库关联，请创建一个 .vscode/mcp.json 文件，并包含以下内容：

{
  "inputs": [],
  "servers": {
     "marvel-mcp": {
         "command": "npx",
         // "command": "node",
         "args": [
             "-y",
             "@codewithdan/marvel-mcp"
             // "/PATH/TO/marvel-mcp/dist/index.js"
         ],
         "env": {
             "MARVEL_PUBLIC_KEY": "YOUR_PUBLIC_KEY",
             "MARVEL_PRIVATE_KEY": "YOUR_PRIVATE_KEY",
             "MARVEL_API_BASE": "https://gateway.marvel.com/v1/public"
         }
     }
  }
}

如果你想将MCP服务器与所有仓库关联，请在VS Code用户设置JSON中添加以下内容：

"mcp": {
 "servers": {
     "marvel-mcp": {
         "command": "npx",
         // "command": "node",
         "args": [
             "-y",
             "@codewithdan/marvel-mcp"
             // "/PATH/TO/marvel-mcp/dist/index.js"
         ],
         "env": {
             "MARVEL_PUBLIC_KEY": "YOUR_PUBLIC_KEY",
             "MARVEL_PRIVATE_KEY": "YOUR_PRIVATE_KEY",
             "MARVEL_API_BASE": "https://gateway.marvel.com/v1/public"
         }
     },
 }
},
"chat.mcp.discovery.enabled": true,

在GitHub Copilot中使用工具

1. 现在MCP服务器已经可以被发现了，打开GitHub Copilot并选择Agent模式（而不是Chat或Edits）。

2. 选择Copilot聊天文本框中的“刷新”按钮以刷新服务器列表。

3. 选择“🛠️”按钮查看所有可能的工具，包括来自此仓库的工具。

4. 在聊天中提出一个问题，自然地调用其中一个工具，例如：

   列出10个漫威角色。包含图片。
   
   金刚狼出现在哪些漫画中？
   
   哪些角色出现在复仇者联盟漫画中？
   
   《Hedge Knight II: Sworn Sword (2007)》漫画中有哪些角色？
   

   注意：如果你看到“抱歉，响应被负责任的人工智能服务过滤了。”的消息，尝试再次运行或重新措辞提示。