mcp-starwars

This MCP server provides a Star Wars API wrapper around the SWAPI data. It exposes a collection of tools you can call to list and fetch details for characters, planets, films, species, vehicles, and starships with built-in pagination and caching. The tools are designed to be used by MCP-enabled clients and editors (like VS Code, Claude, etc.) to fetch data from the SWAPI and return structured results that include related entities and metadata. You can register this MCP server with your MCP tooling to easily discover and query Star Wars entities in your development environment.

To use the tools, you’ll typically call functions like get_people, get_person_by_id, get_planets, get_planet_by_id, get_films, get_film_by_id, get_species_list, get_species_by_id, get_vehicles, get_vehicle_by_id, get_starships, and get_starship_by_id. Most list operations support optional page and search parameters as well as a fetchAllPages flag to automatically retrieve all pages of results. Each detail operation returns comprehensive data for the requested entity, including attributes like name, climate, population, model, manufacturer, and related entities.

Prerequisites:

• Node.js v20 or later installed on your machine
• npm (comes with Node.js) or pnpm/yarn if you prefer

Install via npx (recommended for MCP neighborhood tooling):

1. Ensure Node.js is installed and available in your PATH
2. Run: npx -y @johnpapa/mcp-starwars

Alternative: Docker installation

1. Ensure Docker is running on your system
2. Run: docker run -i --rm mcp/starwars

Environment and configuration

• The MCP server exposes a set of tools (see Tools section in README) and can be configured via environment variables if needed by your setup. The default run uses the npx-based command described above. If you are integrating with a specific MCP host or editor, you may supply env vars as appropriate in your host configuration.

Tips and common considerations:

• The server fetches data from SWAPI, so performance may depend on SWAPI response times and network connectivity. Built-in caching helps reduce repeated calls.
• When using npx, the server runs in a transient environment; persistent configuration can be achieved by integrating with your MCP host's install/config flow.
• If you prefer Docker for isolation, use the Docker command provided in the installation notes and ensure the image name matches your hosting environment (mcp/starwars).
• The tools support automatic pagination by default. Use fetchAllPages=false if you only want a single page.
• Ensure you register the MCP server with any MCP tooling you’re using to discover and invoke the tools easily.