# SWAPI - The Star Wars MCP > SWAPI - The Star Wars lets you query every detail from the Star Wars universe. Use your AI agent to search for specific characters like Luke Skywalker, find technical specs on starships (Millennium Falcon), list all planets (Tatooine, Coruscant), or check film details. It’s a direct API gateway to deep lore data. ## Overview - **Category:** databases - **Price:** Free - **Tags:** star-wars, swapi, pop-culture, encyclopedia, api-data ## Description Listen up. This ain't some fancy widget; this is your direct line into the Star Wars universe data set. You connect your agent and you get straight API access to deep lore stuff that used to take hours of cross-referencing wikis. We got eight tools here, each one letting you drill down into specific facts—from character backstories to hyperdrive ratings. To start broad, you can run `get_root` to pull general resources from the entire SWAPI dataset, giving you a high-level overview of what’s in there. If you already know the exact URL for a piece of data, don't waste time searching; just use `get_resource_by_url`. That lets you jump straight to specific information when you've got the address. When it comes to people and life forms, your agent handles everything. You can search for characters using `list_people`, letting you filter by a name like Luke Skywalker or Darth Vader to pull their complete profiles. If you want to analyze alien biology—the species that inhabit the galaxy—you use `list_species` to find details on creatures and life forms, filtering by the biological classification. You can also check out the worlds themselves; running `list_planets` searches for planets and moons, letting you filter by name or location to get climate and terrain stats. For all things mechanical—the tech of the galaxy—you've got dedicated tools. To find specs on huge war machines, use `list_starships`. This tool gives you model details, max speeds, and hyperdrive ratings for starships like the Millennium Falcon. If you’re looking at smaller gear, like ground transport or personal fighters, you run `list_vehicles` to get data on those specific models. When it comes to media, you don't gotta guess which movies exist. You use `list_films` to search and list all the films in the saga; you can filter that search by title or other parameters to pull general metadata for any movie. Basically, your agent uses these tools—the deep-dive capability of `get_resource_by_url`, the broad overview of `get_root`, the character data from `list_people`, the world details via `list_planets`, the mechanical specs from `list_starships` and `list_vehicles`, the species analysis using `list_species`, and the movie list from `list_films`—to pull every piece of structured lore you need. You're not just reading facts; your agent is performing targeted, functional database queries against the whole Star Wars canon. ## Tools ### get_resource_by_url Retrieves specific Star Wars data when you already know the exact API URL for the resource. ### get_root Fetches general, root-level resources from the entire SWAPI dataset. ### list_films Searches and lists data for Star Wars films, filtering by title or other search parameters. ### list_people Searches and lists information on characters and people within the SWAPI database, filtered by name. ### list_planets Searches and lists data for planets, allowing filtering by planet name or location. ### list_species Searches and lists biological species inhabiting the galaxy, filtered by species name. ### list_starships Searches and lists technical specifications for starships, filtering by model or name. ### list_vehicles Searches and lists data on smaller vehicles (like ground transport), filtered by model or name. ## Prompt Examples **Prompt:** ``` Search for the character 'Darth Vader' and tell me his height. ``` **Response:** ``` I found Darth Vader. According to the records, he is 202 cm tall and weighs 136 kg. ``` **Prompt:** ``` List all the planets in the Star Wars universe. ``` **Response:** ``` Fetching planets... I've found several worlds including Tatooine, Alderaan, Yavin IV, and Hoth. Would you like details on a specific one? ``` **Prompt:** ``` What are the technical specifications of the Millennium Falcon? ``` **Response:** ``` The Millennium Falcon (model YT-1300 light freighter) has a max atmosphering speed of 1050 km/h, a hyperdrive rating of 0.5, and can carry up to 6 passengers. ``` ## Capabilities ### Search for character details List or search for Star Wars characters and people using the `list_people` tool. ### Find planetary data List or search for worlds, retrieving information about planets and moons via `list_planets`. ### Get technical specs on starships Retrieve model details, max speeds, and hyperdrive ratings using the `list_starships` tool. ### Look up specific movie data List or search for films across the saga using the dedicated `list_films` tool. ### Analyze biological species Search and retrieve details on alien life forms and biological species via `list_species`. ### Fetch deep, targeted resources Use the `get_resource_by_url` tool to access specific pieces of data directly from a known API URL. ## Use Cases ### A writer needs character verification. The writer is writing a scene involving Obi-Wan Kenobi and needs his specific homeworld. Instead of guessing or opening multiple tabs, they ask their agent to run `list_people` for 'Obi-Wan Kenobi'. The tool returns the exact planet name (Coruscant), which they drop right into the manuscript. ### A developer needs test data. The dev is building a prototype game and needs mock data for planets. They use `list_planets` to quickly pull a list of worlds (like Alderaan) and their associated climates, allowing them to build out the UI without needing complex backend database setup. ### A lore enthusiast is mapping ships. The user wants to compare the specs of two starships—say, an X-wing versus a freighter. They run `list_starships` and filter by model type. The agent returns technical details like max atmospheric speed and hyperdrive ratings for both in one organized response. ### A student is researching the saga timeline. The student wants to know all films connected to a specific character, say Han Solo. They ask their agent to use `list_people` and then follow up using `get_resource_by_url` based on the resulting data points, mapping out his entire filmography. ## Benefits - Instantly verify complex lore details. Instead of searching through multiple wikis for Darth Vader's height or weight, your agent runs `list_people` and gives you the exact recorded number. - Build detailed world maps with certainty. Use `list_planets` to pull data on climate and terrain for worlds like Hoth, giving you structured data points instead of vague descriptions. - Keep your scripts consistent. Need to confirm if the Millennium Falcon (YT-1300) can carry six people? Run `list_starships` and get its precise passenger capacity stat. - Save time on research projects. Your agent doesn't just list films; it connects them using tools like `get_resource_by_url`, letting you trace data from a character back to the films they were in, all in one go. - Get structured lists of everything. Need every species or every vehicle model? Use `list_species` or `list_vehicles` to get clean, filterable JSON output ready for your code. ## How It Works The bottom line is, your AI client talks to this server, which translates natural language questions into specific API calls, giving you facts on demand. 1. Subscribe to the SWAPI MCP Server. No API key is needed—SWAPI uses public endpoints. 2. Tell your AI client what you need (e.g., 'What is the hyperdrive rating of the Millennium Falcon?'). 3. Your agent runs the appropriate tool (`list_starships`) and returns a structured answer with all the lore details. ## Frequently Asked Questions **How do I find technical specs for a specific ship using list_starships?** You run `list_starships` and include the model name or number in your search parameter. The tool returns detailed stats, including hyperdrive rating and max atmospheric speed. **What is get_resource_by_url for SWAPI?** Use `get_resource_by_url` when you know the exact API endpoint. It bypasses search queries and pulls data directly from that specific URL, which is useful for deep linking. **Can I list all planets in Star Wars?** Yes, use `list_planets`. You can filter the results by name or run it without a parameter to get a comprehensive list of known worlds. **How does list_people work for character data?** The `list_people` tool searches for characters by name. It returns biographical details like height, weight, and homeworld, giving you structured character facts. **Does running a search using `list_films` require an API key or special authentication?** No, you don't need any keys. SWAPI is a free, public resource that your AI client queries directly. You can start listing and searching films immediately without setting up credentials. **What happens if I use `list_people` to search for a character who doesn't exist?** The tool handles this gracefully by returning an empty data set or a clear error message. Your agent receives structured feedback, letting you know no matches were found for that name. **After getting planet data using `list_planets`, how do I find the species native to it?** You take the homeworld reference from the planet record and use it as a filter parameter within the `list_species` tool. This lets you accurately trace a world's biological inhabitants. **If I run many searches using `list_vehicles` in quick succession, are there rate limits?** While SWAPI is highly accessible, excessive calls can trigger temporary throttling. It's best practice for your agent to build a small delay between successive requests to ensure smooth performance. **How can I find a specific character by their name?** You can use the `list_people` tool and provide the name in the `search` parameter. The agent will return all matching characters from the Star Wars universe. **How do I get more details about a URL found in a result (like a homeworld)?** Use the `get_resource_by_url` tool. Simply pass the full URL (e.g., https://swapi.dev/api/planets/1/) to fetch the complete metadata for that specific resource. **Can I search for starships using their model name instead of their common name?** Yes! The `list_starships` tool allows searching by both name and model. Just enter the model string into the `search` parameter.