# 漫威MCP服务
## 基本信息
- Slug: `danwahlin-marvel-mcp`
- Source: modelscope
- Publisher: @DanWahlin/marvel-mcp
- Categories: search / art-and-culture
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@DanWahlin/marvel-mcp
## 简介
用于漫威开发者API的MCP服务器，支持与角色和漫画数据进行交互。
## 安装提示

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

## MCP Server 详情

<div align="center">

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

# Marvel MCP 服务器

[![在 GitHub Codespaces 中打开项目](https://img.shields.io/badge/Codespaces-Open-blue?style=flat-square&logo=github)](https://codespaces.new/danwahlin/marvel-mcp?hide_repo_select=true&ref=main&quickstart=true)
![Node 版本](https://img.shields.io/badge/Node.js->=20-3c873a?style=flat-square)
[![smithery 徽章](https://smithery.ai/badge/@DanWahlin/marvel-mcp)](https://smithery.ai/server/@DanWahlin/marvel-mcp)
[![许可证](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)

[功能](#features) • [工具](#tools) • [设置](#setup) • [配置 MCP 主机](#configuring-an-mcp-host)

</div>

用于 [Marvel 开发者 API](https://developer.marvel.com/documentation/getting_started) 的 MCP 服务器，能够与角色和漫画数据进行交互。*该项目的主要目标是展示如何使用 MCP 服务器与 API 进行交互。*

> **注意**：此 MCP 服务器使用的所有数据均来自 [官方 Marvel API](https://developer.marvel.com/documentation/getting_started)，并由 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](https://developer.marvel.com/documentation/getting_started) 账户并获取您的公共和私有 API 密钥。

如果您想直接在 MCP 主机上运行，请跳转到 [与 Claude Desktop 一起使用](#use-with-claude-desktop) 或 [与 GitHub Copilot 一起使用](#use-with-github-copilot) 部分。

### 使用 MCP Inspector 本地运行服务器

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

1. 克隆此仓库：

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

1. 将 `.env.template` 重命名为 `.env`。

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

    ```bash
    MARVEL_PUBLIC_KEY=YOUR_PUBLIC_KEY
    MARVEL_PRIVATE_KEY=YOUR_PRIVATE_KEY
    MARVEL_API_BASE=https://gateway.marvel.com/v1/public
    ```
1. 安装所需的依赖项并构建项目。

    ```bash
    npm install
    npm run build
    ```

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

    ```bash
    # 启动 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` 文件中：

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