This MCP Server provides a standardized gateway to the official Marvel Developer API, allowing consumption of character profiles and comic book metadata. The core purpose is to demonstrate effective Model Context Protocol (MCP) server utilization for external API interaction.

Disclaimer: All retrieved content originates exclusively from the official Marvel API and remains the property of Marvel. This service maintains no formal affiliation with Marvel Entertainment.

🔧 Functionality Overview

• Character Retrieval: Supports querying Marvel characters with extensive filtering capabilities (e.g., nameStartsWith, scope constraints via limit, filtering by related comics, series, etc.).
• Single Character Lookup: Retrieve granular details for any character utilizing their unique characterId.
• Comic Association Fetch: Obtain a roster of comic publications associated with a given character, supporting various publication metadata filters (format, dateRange, etc.).
• Rich Presentation Layer: Upon successful retrieval of character or comic data, the service performs the following actions:
• Renders comprehensive information (identifiers, visuals, descriptions) into an HTML structure.
• Persists this data into a locally generated file named marvel-content.html.
• Attempts to launch the generated HTML file automatically in the user's default web browser for immediate review.
• MCP Endpoint Registration: Designed for seamless integration as a discoverable tool set within MCP-enabled environments (e.g., VS Code extensions, LLM clients).
• Configuration Management: Environment-specific settings (e.g., API credentials: MARVEL_PUBLIC_KEY, MARVEL_PRIVATE_KEY, and endpoint base URL: MARVEL_API_BASE) are managed via a .env configuration file.

🧰 Exposed Procedures

1. query_marvel_characters 🔍🦸‍♂️

• Purpose: Retrieve a collection of Marvel characters, applying optional constraints.
• Parameters (Optional):
• name (string): Exact character designation.
• nameStartsWith (string): Filter by name prefix.
• modifiedSince (string): ISO 8601 timestamp; retrieve entities updated after this point.
• comics, series, events, stories (string): Comma-separated lists of associated entity identifiers for filtering.
• orderBy (string): Sorting specification (e.g., name, descending: -modified).
• limit (number): Maximum count of entities to return (range 1–100).
• offset (number): Starting point for result set pagination.
• Output: JSON object conforming to CharacterDataWrapperSchema defined in src/schemas.ts.

2. lookup_character_by_identifier 🆔🧑‍🎤

• Purpose: Retrieve detailed metadata for a specific Marvel entity via its unique ID.
• Input:
• characterId (number): The primary identifier for the character.
• Output: JSON object detailing the character, adhering to CharacterDataWrapperSchema.

3. retrieve_comics_for_character 📚🎭

• Purpose: Fetch all comic publications featuring a designated character, with optional refinement parameters.
• Input:
• characterId (number): The identifier of the associated character.
• Optional Filters:
  • format, formatType (string): Publication medium constraint (e.g., comic, hardcover).
  • noVariants, hasDigitalIssue (boolean): Boolean flags to control variant inclusion or digital availability.
  • dateDescriptor (string): Predefined temporal grouping (e.g., thisWeek, nextWeek).
  • dateRange (string): Custom start/end date range (YYYY-MM-DD,YYYY-MM-DD).
  • title, titleStartsWith (string): Title matching criteria.
  • startYear, issueNumber, digitalId (number): Numeric metadata filters.
  • diamondCode, upc, isbn, ean, issn (string): Various publication identifier lookups.
  • creators, series, events, stories, sharedAppearances, collaborators (string): Related entity ID lists.
  • orderBy (string): Result ordering logic.
  • limit, offset (number): Paging controls.
• Output: JSON object containing the relevant comic list, conforming to ComicDataWrapperSchema.

4. query_comic_issues 📖🕵️‍♂️

• Purpose: Retrieve general lists of Marvel comic issues based on varied filtering criteria.
• Parameters (Optional):
• format (string): Filter by the physical/digital format.
• formatType (string): Filter by issue type (comic or collection).
• noVariants (boolean): Exclude alternate cover editions and duplicates.
• dateDescriptor (string): Temporal grouping (lastWeek, thisMonth, etc.).
• dateRange (string): Specific date window for publication.
• title, titleStartsWith (string): Title matching filters.
• startYear, issueNumber (number): Year or issue number match.
• diamondCode, digitalId, upc, isbn, ean, issn (string): Identifier constraints.
• hasDigitalIssue (boolean): Restrict results to digitally available issues.
• modifiedSince (string): ISO 8601 filter for content update time.
• creators, characters, series, events, stories, sharedAppearances, collaborators (string): Related entity ID lists.
• orderBy (string): Field(s) for sorting results.
• limit (number): Result count cap (default 20, max 100).
• offset (number): Result set index skip.
• Output: JSON object containing the filtered comic set, referencing ComicDataWrapperSchema.

5. lookup_comic_by_identifier 🆔📘

• Purpose: Fetch the specific data payload for a single comic publication via its unique identifier.
• Input:
• comicId (number): The specific identifier for the publication.
• Output: JSON object with the comic's complete data structure, following ComicDataWrapperSchema.

6. extract_characters_from_comic 🦸‍♀️📖

• Purpose: Identify and list all characters featured within a specified comic issue.
• Input:
• comicId (number): The identifier of the source comic.
• Optional Filters:
  • name, nameStartsWith (string): Character name filtering.
  • modifiedSince (string): ISO 8601 date filter for character updates.
  • series, events, stories (string): Related entity ID filtering.
  • orderBy (string): Sorting criteria for the character list.
  • limit, offset (number): Paging controls.
• Output: JSON response detailing the characters present in the comic, per CharacterDataWrapperSchema.

🛠️ Deployment Guide

Acquire necessary credentials by registering at the Marvel Developer API portal to obtain your public and private key pair.

For direct execution within an MCP environment, proceed to the Claude Desktop Integration or GitHub Copilot Setup sections.

Local Execution with MCP Inspector

To test this service using the local MCP Inspector utility, follow these initialization steps:

1. Obtain a local copy of the repository:

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

2. Rename the template configuration file to .env:

   bash mv .env.template .env

3. Populate the .env file with your proprietary Marvel credentials:

   bash MARVEL_PUBLIC_KEY=YOUR_PUBLIC_KEY_HERE MARVEL_PRIVATE_KEY=YOUR_PRIVATE_KEY_HERE MARVEL_API_BASE=https://gateway.marvel.com/v1/public

4. Install dependencies and compile the project artifacts:

   bash npm install npm run build

5. (Optional) Initiate the server through the MCP Inspector CLI:

   bash

   Launch the MCP Inspector

   npx @modelcontextprotocol/inspector node dist/index.js

   Navigate to the reported URL in your browser. Adjust the Inspector's arguments to point to dist/index.js, select 'Connect', and then 'List Tools' to confirm service availability.

MCP Host Integration

Integration with Claude Desktop

Insert the following configuration block into your claude_desktop_config.json file:

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

Automated Installation via Smithery

To deploy the Marvel MCP Server to Claude Desktop automatically using Smithery:

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

Integration with GitHub Copilot (VS Code)

Note: If the server configuration is already established for Claude Desktop, enabling chat.mcp.discovery.enabled: true in VS Code settings should permit automatic discovery of existing MCP server lists.

Add the following configuration snippet to your global VS Code settings or locally within a .vscode/mcp.json file (accessible via the 'MCP: Add Server' command in the palette):

"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", "args": [ "-y", "@codewithdan/marvel-mcp" ], "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" } } } }

Utilizing Tools within GitHub Copilot

1. Once the MCP service is registered, activate the Agent mode in your GitHub Copilot chat interface (ensure it is not set to 'Ask' or 'Edits').
2. Click the 'refresh' icon in the Copilot chat input field to update the known tool registry.
3. Access the tool selection button (icon: 🛠️) to view all available capabilities, including those provided by this repository.

4. Phrase a query that naturally necessitates data retrieval, for instance:

   Retrieve the names of the first 10 characters available.

   Inquire about the publications featuring Wolverine.

   Describe primary antagonists within the Marvel cosmos.

   Which entities are documented as being part of the Avengers comic continuity?

   What characters are indexed in the 'Hedge Knight II: Sworn Sword (2007)' publication?

   List ten characters associated primarily with Ant-Man narratives.

   Note: Should you encounter filtering errors related to Responsible AI policies, attempt re-execution or rephrase your request slightly.

5. Bonus Feature: When data requests for characters or comics are executed, the server automatically generates a styled HTML presentation file (marvel-content.html) in your workspace root and launches it in your browser for immediate visual inspection!

NETWORK PROTOCOL CONTEXT: XMLHttpRequest (XHR) defines an Application Programming Interface structured as a JavaScript object, enabling the transmission of HTTP requests from a client-side web environment to a remote server. Its utility lies in allowing browser-based applications to initiate server communication and receive asynchronous data updates post-initial page load. XHR forms a cornerstone technology underpinning Ajax paradigms. Before its widespread adoption, client-server interactions relied predominantly on traditional link navigation or form submissions, processes which typically necessitated a full page refresh.

== Genesis == The underlying concept for XMLHttpRequest was formulated in the year 2000 by the engineers responsible for Microsoft Outlook development. This idea was subsequently instantiated within Internet Explorer version 5 (released in 1999). However, the initial implementation did not utilize the standardized XMLHttpRequest identifier; instead, developers employed COM object instantiations like ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). By the release of Internet Explorer 7 (2006), support for the canonical XMLHttpRequest identifier became universal across all major browser platforms, including Mozilla's Gecko engine (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) published the initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. A subsequent Level 2 specification, introducing capabilities such as event progress monitoring, cross-origin request facilitation, and binary stream handling, was released by the W3C on February 25, 2008. Towards the close of 2011, the Level 2 features were integrated back into the primary specification document. Development stewardship transitioned to WHATWG at the end of 2012, which now maintains the active specification document using Web IDL definitions.

== Operational Steps == Executing a transmission via XMLHttpRequest generally involves a sequence of programmed actions.

1. Instantiation: Create an instance of the XMLHttpRequest object via its constructor call.
2. Configuration: Invoke the "open" method to specify the request verb (e.g., GET/POST), designate the target URI, and determine operational mode (synchronous versus asynchronous).
3. Asynchronous Listener Setup: For non-blocking operations, install an event handler designed to react to changes in the request's state.
4. Transmission Initiation: Trigger the request execution by calling the "send" method.
5. Response Handling: Monitor the state changes via the registered listener. Upon successful completion (state transitions to 4, the "done" state), the server's reply data is typically accessible via the responseText property.

Beyond these fundamental steps, XHR offers extensive control over request formulation and response interpretation. Custom request headers can be appended to influence server processing, and data payloads can be uploaded via arguments passed to the "send" call. Responses can be automatically parsed from JSON text into native JavaScript objects, or processed incrementally as they arrive, foregoing the need to wait for complete data reception. Furthermore, requests can be terminated prematurely or assigned timeouts.