Marvel MCP Server

Interaja com a Marvel Developer API para acessar dados sobre personagens e quadrinhos.

Documentação

Marvel MCP Server

Recursos • Ferramentas • Configuração • Configurando um Host MCP

NOTA: A Marvel recentemente aposentou sua API, então ela não está mais disponível, infelizmente. Estou deixando este repositório no ar por motivos históricos, já que a abordagem ainda é relevante para servidores MCP. Se você quiser ver um exemplo semelhante, confira meu servidor MCP da DC Comics.

Servidor MCP para a Marvel Developer API, permitindo interação com dados de personagens e quadrinhos. O principal objetivo do projeto é mostrar como um servidor MCP pode ser usado para interagir com APIs.

Nota: Todos os dados usados por este servidor MCP são obtidos da API oficial da Marvel e pertencem à Marvel. Este projeto não é afiliado à Marvel de forma alguma.

🔧 Recursos

Listar Personagens da Marvel: Suporta filtros como nameStartsWith, limit, comics, series, etc.
Buscar um Personagem da Marvel por ID: Obtenha informações detalhadas sobre qualquer personagem usando seu characterId.
Buscar Quadrinhos para um Personagem: Obtenha uma lista de quadrinhos com um personagem específico, com vários filtros como format, dateRange, etc.
Exibição de Conteúdo Rico: Quando você perguntar sobre personagens ou quadrinhos, o servidor irá:
- Exibir informações detalhadas sobre personagens e quadrinhos, incluindo imagens, nomes, descrições e mais.
- Criar uma página HTML (marvel-content.html) com todo o conteúdo nela.
- Tentar abrir a página HTML recém-criada no seu navegador padrão para uma experiência de visualização aprimorada.
Integração MCP baseada em ferramentas: Registre este servidor com ferramentas do Model Context Protocol (MCP) (VS Code, Claude, etc.).
Configuração de Ambiente: Use o arquivo .env para gerenciar variáveis de ambiente como MARVEL_PUBLIC_KEY, MARVEL_PRIVATE_KEY e MARVEL_API_BASE.

🧰 Ferramentas

1. `get_characters` 🔍🦸‍♂️

Descrição: Busca personagens da Marvel com filtros opcionais.
Entradas:
- name (string opcional): Nome completo do personagem.
- nameStartsWith (string opcional): Personagens cujos nomes começam com a string especificada.
- modifiedSince (string opcional): String de data ISO 8601 para filtrar personagens modificados desde esta data.
- comics, series, events, stories (string opcional): Lista separada por vírgulas de IDs para filtrar por entidades relacionadas.
- orderBy (string opcional): Campos para ordenar os resultados, como name ou -modified.
- limit (número opcional): Número máximo de resultados a retornar (1–100).
- offset (número opcional): Número de resultados a pular para paginação.
Retorna: Resposta JSON com personagens correspondentes. Consulte CharacterDataWrapperSchema em src/schemas.ts para obter detalhes.

2. `get_character_by_id` 🆔🧑‍🎤

Descrição: Busca um personagem da Marvel pelo seu ID único.
Entrada:
- characterId (número): O ID único do personagem.
Retorna: Resposta JSON com os detalhes do personagem. Consulte CharacterDataWrapperSchema em src/schemas.ts para obter detalhes.

3. `get_comics_for_character` 📚🎭

Descrição: Busca quadrinhos com um personagem específico, com filtros opcionais.
Entradas:
- characterId (número): O ID único do personagem.
- Filtros opcionais:
  - format, formatType (string): Filtrar por formato de quadrinho (ex.: comic, hardcover).
  - noVariants, hasDigitalIssue (booleano): Sinalizadores para excluir variantes ou incluir apenas edições digitais.
  - dateDescriptor (string): Intervalos de datas predefinidos como thisWeek, nextWeek.
  - dateRange (string): Intervalo de datas personalizado no formato YYYY-MM-DD,YYYY-MM-DD.
  - title, titleStartsWith (string): Filtrar por título ou prefixo do título.
  - startYear, issueNumber, digitalId (número): Filtros numéricos.
  - diamondCode, upc, isbn, ean, issn (string): Filtros de identificador.
  - creators, series, events, stories, sharedAppearances, collaborators (string): Lista separada por vírgulas de IDs de entidades relacionadas.
  - orderBy (string): Campos para ordenar os resultados, como title ou -modified.
  - limit, offset (número): Opções de paginação.
Retorna: Resposta JSON com quadrinhos com o personagem especificado. Consulte ComicDataWrapperSchema em src/schemas.ts para obter detalhes.

4. `get_comics` 📖🕵️‍♂️

Descrição: Busca listas de quadrinhos da Marvel com filtros opcionais.
Entradas:
- format (string opcional): Filtrar pelo formato da edição (ex.: comic, digital comic, hardcover).
- formatType (string opcional): Filtrar pelo tipo de formato da edição (comic ou collection).
- noVariants (booleano opcional): Excluir variantes (capas alternativas, impressões secundárias, cortes do diretor, etc.) do conjunto de resultados.
- dateDescriptor (string opcional): Retornar quadrinhos dentro de um intervalo de datas predefinido (lastWeek, thisWeek, nextWeek, thisMonth).
- dateRange (string opcional): Retornar quadrinhos dentro de um intervalo de datas personalizado. As datas devem ser especificadas como YYYY-MM-DD,YYYY-MM-DD.
- title (string opcional): Retornar apenas edições em séries cujo título corresponda à entrada.
- titleStartsWith (string opcional): Retornar apenas edições em séries cujo título comece com a entrada.
- startYear (número opcional): Retornar apenas edições em séries cujo ano de início corresponda à entrada.
- issueNumber (número opcional): Retornar apenas edições em séries cujo número da edição corresponda à entrada.
- diamondCode, digitalId, upc, isbn, ean, issn (string opcional): Filtrar por vários identificadores.
- hasDigitalIssue (booleano opcional): Incluir apenas resultados disponíveis digitalmente.
- modifiedSince (string opcional): Retornar apenas quadrinhos que foram modificados desde a data especificada (formato ISO 8601).
- creators, characters, series, events, stories, sharedAppearances, collaborators (string opcional): Lista separada por vírgulas de IDs para filtrar por entidades relacionadas.
- orderBy (string opcional): Ordene o conjunto de resultados por um ou mais campos. Adicione um "-" ao valor para classificar em ordem decrescente (ex.: title, -modified).
- limit (número opcional): Limite o conjunto de resultados ao número especificado de recursos (padrão: 20, máximo: 100).
- offset (número opcional): Pule o número especificado de recursos no conjunto de resultados.
Retorna: Resposta JSON com quadrinhos correspondentes. Consulte ComicDataWrapperSchema em src/schemas.ts para obter detalhes.

5. `get_comic_by_id` 🆔📘

Descrição: Busca um único quadrinho da Marvel pelo seu ID único.
Entrada:
- comicId (número): O ID único do quadrinho.
Retorna: Resposta JSON com os detalhes do quadrinho. Consulte ComicDataWrapperSchema em src/schemas.ts para obter detalhes.

6. `get_characters_for_comic` 🦸‍♀️📖

Descrição: Busca personagens da Marvel que aparecem em um quadrinho específico.
Entradas:
- comicId (número): O ID único do quadrinho.
- Filtros opcionais:
  - name (string opcional): Filtrar personagens por nome completo.
  - nameStartsWith (string opcional): Filtrar personagens cujos nomes começam com a string especificada.
  - modifiedSince (string opcional): String de data ISO 8601 para filtrar personagens modificados desde esta data.
  - series, events, stories (string opcional): Lista separada por vírgulas de IDs de entidades relacionadas para filtrar.
  - orderBy (string opcional): Campos para ordenar os resultados, como name ou -modified.
  - limit (número opcional): Número máximo de resultados a retornar (1–100).
  - offset (número opcional): Número de resultados a pular para paginação.
Retorna: Resposta JSON com personagens que aparecem no quadrinho especificado. Consulte CharacterDataWrapperSchema em src/schemas.ts para obter detalhes.

🛠️ Configuração

Cadastre-se para obter uma conta na Marvel Developer API e obtenha suas chaves de API pública e privada.

Se você quiser executá-lo diretamente em um host MCP, vá para as seções Uso com Claude Desktop ou Uso com GitHub Copilot.

Executar o Servidor Localmente com o MCP Inspector

Se você quiser executar o MCP Inspector localmente para testar o servidor, siga estas etapas:

Clone este repositório:

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

Renomeie .env.template para .env.

Adicione suas chaves pública e privada da Marvel API ao arquivo .env.

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

Instale as dependências necessárias e compile o projeto.
```
npm install
npm run build
```
(Opcional) Para testar o servidor usando o MCP Inspector, execute o seguinte comando:
```
# Start the MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js
```
Visite a URL do MCP Inspector exibida no console em seu navegador. Altere Arguments para dist/index.js e selecione Connect. Selecione List Tools para ver as ferramentas disponíveis.

Configurando um Host MCP

Uso com Claude Desktop

Adicione o seguinte ao seu 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"
      }
    }
  }
}

Instalação via Smithery

Para instalar o Marvel MCP Server para Claude Desktop automaticamente via Smithery:

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

Uso com GitHub Copilot

Nota: Se você já tem o servidor MCP habilitado com o Claude Desktop, adicione chat.mcp.discovery.enabled: true nas configurações do VS Code e ele descobrirá as listas de servidores MCP existentes.

Adicione o seguinte ao seu arquivo de configurações do usuário ou adicione-o ao arquivo .vscode/mcp.json se você quiser que ele esteja disponível apenas neste repositório (você pode usar MCP: Add Server na paleta de comandos e selecionar Global ou Workspace):

"mcp": {
  "inputs": [
      {
          "type": "promptString",
          "id": "marvel-public-api-key",
          "description": "Marvel public API Key",
          "password": true
      },
      {
          "type": "promptString",
          "id": "marvel-private-api-key",
          "description": "Marvel private API Key",
          "password": true
      }
  ],
  "servers": {
    "marvel-mcp": {
        "command": "npx",
        // "command": "node",
        "args": [
            "-y",
            "@codewithdan/marvel-mcp"
            // "/PATH/TO/marvel-mcp/dist/index.js"
        ],
        "env": {
            "MARVEL_PUBLIC_KEY": "${input:marvel-public-api-key}",
            "MARVEL_PRIVATE_KEY": "${input:marvel-private-api-key}",
            "MARVEL_API_BASE": "https://gateway.marvel.com/v1/public"
        }
    }
  }
}

Usando Ferramentas no GitHub Copilot

Agora que o servidor MCP está detectável, abra o GitHub Copilot e selecione o modo Agent (não Ask ou Edits).
Selecione o botão "refresh" no campo de texto do chat do Copilot para atualizar a lista de servidores.
Selecione o botão "🛠️" para ver todas as ferramentas possíveis, incluindo as deste repositório.

Faça uma pergunta no chat que naturalmente invoque uma das ferramentas, por exemplo:

List 10 marvel characters.

What comics is Wolverine in?

Give me details about villains in the Marvel universe.

Which characters appear in the Avengers comics?

What characters are in the Hedge Knight II: Sworn Sword (2007) comic?

List 10 characters from Ant-Man comics.

Nota: Se você vir "Desculpe, a resposta foi filtrada pelo Responsible AI Service.", tente executar novamente ou reformular a pergunta.

Bônus: Quando você perguntar sobre personagens ou quadrinhos, o servidor criará automaticamente um arquivo marvel-content.html na raiz do seu projeto com uma página lindamente estilizada contendo todas as informações e imagens do personagem/quadrinho e a abrirá no seu navegador!

Marvel MCP Server

Documentação

Marvel MCP Server

🔧 Recursos

🧰 Ferramentas

1. get_characters 🔍🦸‍♂️

2. get_character_by_id 🆔🧑‍🎤

3. get_comics_for_character 📚🎭

4. get_comics 📖🕵️‍♂️

5. get_comic_by_id 🆔📘

6. get_characters_for_comic 🦸‍♀️📖

🛠️ Configuração

Executar o Servidor Localmente com o MCP Inspector

Configurando um Host MCP

Uso com Claude Desktop

Instalação via Smithery

Uso com GitHub Copilot

Usando Ferramentas no GitHub Copilot

1. `get_characters` 🔍🦸‍♂️

2. `get_character_by_id` 🆔🧑‍🎤

3. `get_comics_for_character` 📚🎭

4. `get_comics` 📖🕵️‍♂️

5. `get_comic_by_id` 🆔📘

6. `get_characters_for_comic` 🦸‍♀️📖