<div align="center"> <img src="./images/captain-america.jpg" alt="" align="center" height="96" />

Marvel MCP 服务器

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

</div>

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

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

<a name="features"></a>

🔧 功能

• 列出 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 等环境变量。

<a name="tools"></a>

🧰 工具

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。

<a name="setup"></a>

🛠️ 设置

注册一个 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 查看可用工具。

<a name="configuring-an-mcp-host"></a>

配置 MCP 主机

与 Claude Desktop 一起使用

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

{
  "mcpServers": {
    "marvel-mcp": {
      "type":…