# SuperHero MCP > SuperHero MCP Server gives your AI agent instant access to a comic book database spanning Marvel, DC, and more. Use this server to search characters by name, compare power stats (strength, speed, durability), retrieve biographies, map connections to other heroes, or get their official portrait image URL. ## Overview - **Category:** knowledge-management - **Price:** Free - **Tags:** superheroes, comics, marvel, dc-comics, character-database, power-levels ## Description This server hooks your agent directly into a massive comic book database covering Marvel, DC, and other major universes. You're not dealing with fuzzy APIs here; you get structured data for every hero and villain. When you need info on any character, the process starts by calling `search_characters` with a name. This function returns multiple potential matches along with their unique IDs—that ID is what you use for everything else. Once your agent has that specific ID, it can pull deep details. You can grab all known information fields about a single character using `get_character`. Need to know who they are? `get_biography` pulls key background data like their full names, aliases, and when they first appeared in print. For the physical rundown—race, height, weight—you call `get_appearance`. Want to compare heroes on paper? You use `get_powerstats`, which provides a numeric breakdown of metrics including strength, speed, and durability scores for direct comparison. If you need to know what they look like right now, `get_image` grabs the direct URL for their portrait image. You're not just getting stats; you're mapping out whole universes. To see who's in their circle—other people or groups associated with them—you use `get_connections`. If you need to know what organizations they belong to, like a specific team or government agency, the server tracks that using `get_work`. Every figure has an ID; these tools let your agent chain together multiple lookups. For instance, after finding a hero's ID with `search_characters`, your agent can immediately call `get_powerstats` and then use that same ID to run both `get_connections` and `get_work` in one sequence. You'll see the character’s full context—their core data via `get_character`, their history via `get_biography`, their physical build from `get_appearance`, their social network through **`get_connections`** or **`get_work`**, and their visual identity using **`get_image`**. You're working with a complete, cross-referenced character profile for every single entry. ## Tools ### get_appearance Retrieves the physical details—race, height, weight, etc.—for one character ID. ### get_biography Pulls key background data like full names, aliases, and first appearances for a specific character. ### get_character Returns all known information fields about a single character ID in one call. ### get_connections Lists people or groups associated with the character's network using their unique ID. ### get_image Grabs the direct URL for the character’s portrait image. ### get_powerstats Provides a numeric breakdown of a character's metrics, including strength and durability scores. ### get_work Details the specific groups or organizations a character belongs to using their ID. ### search_characters Searches the database by name and returns multiple potential matches along with their IDs. ## Prompt Examples **Prompt:** ``` Search for characters named 'Batman' and show me their IDs. ``` **Response:** ``` I found several matches for 'Batman'. The main Bruce Wayne version is ID 70 (DC Comics). There is also a Terry McGinnis version (ID 71). Which one would you like to explore? ``` **Prompt:** ``` What are the powerstats for character ID 332? ``` **Response:** ``` For Hulk (ID 332), the powerstats are: Intelligence: 88, Strength: 100, Speed: 63, Durability: 100, Power: 98, and Combat: 85. He is at maximum level for strength and durability. ``` **Prompt:** ``` Get the full biography and image for character ID 620. ``` **Response:** ``` Character ID 620 is Spider-Man (Peter Parker). He first appeared in Amazing Fantasy #15 and is published by Marvel Comics. I've also retrieved his portrait image URL for you. ``` ## Capabilities ### Search Characters You can find any hero or villain by name using `search_characters`, which returns a unique ID needed for all other lookups. ### Analyze Power Stats The `get_powerstats` tool retrieves specific metrics—like strength, speed, and durability—for comparison between characters. ### Get Core Character Data Use `get_character` to pull all available information about a character once you have their unique ID. ### Map Connections and Work History The server tracks relationships, allowing you to list group affiliations (`get_work`) or relative connections (`get_connections`) for any given figure. ### Retrieve Visual Assets You can pull the specific portrait image URL using `get_image` so your client knows what the character looks like. ## Use Cases ### Writing a 'What If' Scenario A writer needs to write about Captain America fighting Iron Man. They first use `search_characters` for both names. Then, they call `get_powerstats` on both IDs and feed the raw scores into their agent. The result lets them build conflict based on measurable numbers (e.g., 'Iron Man's tech score beats Cap's durability by 20 points'). ### Populating a Character Database A game dev is building an encyclopedia entry for the Avengers roster. They use `search_characters` to get all relevant IDs, then loop through them calling `get_appearance`, `get_biography`, and `get_work` sequentially. The agent compiles one massive, structured JSON object ready for export. ### Checking Lore Consistency A student is doing a paper on the relationship between two heroes. They use `search_characters` to find both IDs, then call `get_connections` on one ID and cross-reference those names with the other hero's known connections. This validates if their story line makes sense based on published lore. ### Building a Character Profile Sheet A content creator needs to quickly assemble a profile sheet for Spider-Man. They call `get_character` once, then follow up with `get_powerstats`, `get_image`, and `get_work`. The agent compiles all these tools' outputs into one clean summary document. ## Benefits - Stop cross-referencing wikis. You can pull a character’s full history—aliases, first appearance, and alignment—using `get_biography` in seconds, giving you instant story facts. - Comparing heroes is easy. Instead of guessing, use the `get_powerstats` tool to get precise numbers for intelligence, speed, and durability across any two characters you pick. - Building a character relationship tree? Call `get_connections` or `get_work`. It maps out who they work with or their known relatives without manual lookup. - Need an image reference fast? The `get_image` tool grabs the direct portrait URL, letting your agent include visual context right in the response. This is faster than searching a database for assets. - The best part is starting point: Use `search_characters`. It gives you multiple potential IDs (like different versions of Batman) so you don't guess which character you need. ## How It Works The bottom line is: you find an ID, then you call a tool with that ID. The server gives back clean data. 1. First, use `search_characters` to find a character's unique ID based on their name. 2. Next, pass that ID into the desired tool (e.g., `get_powerstats`) to pull specific data points or relationships. 3. Your AI client receives the structured JSON output from the server and uses it for its next action. ## Frequently Asked Questions **How do I start using SuperHero MCP Server? (Using search_characters)** You start by running `search_characters('Name')`. This tool searches the database by name and gives you a list of potential matches, including their unique IDs. You must use one of these returned IDs for all other tools. **What is better: get_character or get_biography for basic info?** `get_character` pulls every single known field about the character ID. `get_biography` focuses specifically on background details like aliases and first appearances. Use both if you need a complete picture. **Can I compare power stats across different universes?** Yes, that’s what it's for. You use `get_powerstats` by calling the tool multiple times with different IDs (e.g., one ID from DC and one from Marvel). The agent compiles a direct comparison. **What if I don't know the character name?** The server requires an initial search by name. If you only have fragmented data, try to find any associated ID or group name first, as `search_characters` is limited to names. **How do I authenticate my request when calling get_character?** It requires a valid SuperHero API Access Token configured in your Vinkius environment variables. You pass this token to authenticate every tool call, ensuring secure access to the character data. **If I use search_characters and then get_connections, how do I map the IDs?** You must pass the unique Character ID retrieved from `search_characters` into all subsequent tools, including `get_connections`. This ID is mandatory; it links the data across multiple endpoints accurately. **If I run get_powerstats repeatedly, how do I handle rate limits?** You should implement a backoff mechanism in your agent logic. The system returns a specific 429 error code when you exceed limits, telling you exactly how long to wait before retrying the call. **What data format do I receive from get_appearance?** The result is a structured JSON object containing precise attributes. Instead of general text, you get specific metrics for race, height, weight, and separate fields for eye/hair color. **How do I find the ID for a specific character like Spider-Man?** Use the `search_characters` tool with the name 'spider-man'. The agent will return a list of matches including their unique numeric IDs, which you can then use for detailed queries. **Can I compare the strength and speed of two different characters?** Yes! You can ask the agent to run `get_powerstats` for multiple character IDs. It will retrieve intelligence, strength, speed, durability, power, and combat stats for comparison. **Does this integration allow me to see what teams a hero belongs to?** Absolutely. Use the `get_connections` tool with a character ID to see their group affiliations and known relatives.