An MCP server for the SWAPI Star Wars API, demonstrating how an MCP server can wrap a REST API with built-in caching and pagination. It exposes 14 tools: get_people, get_planets, get_films, get_species_list, get_vehicles, and get_starships each list their category with automatic pagination and optional search; get_person_by_id, get_planet_by_id, get_film_by_id, get_species_by_id, get_vehicle_by_id, and get_starship_by_id each retrieve one record's full detail by ID; and clear_cache and get_cache_stats manage and report on the server's internal API response cache. Automatic pagination means a single tool call retrieves all pages of a listing rather than requiring the caller to page through results manually, and caching means repeated lookups avoid re-hitting the upstream SWAPI API.

Use it when an AI assistant needs to look up Star Wars characters, planets, films, species, vehicles, or starships - listing with search, or fetching one record's full detail by ID. It also serves as a reference example for how to structure an MCP server around a REST API with pagination and caching baked in. It requires Node.js 20 or higher; all data is sourced from the public SWAPI documentation.

The naming follows a get_<category>/get_<category>_by_id shape, but it is not fully regular across all six categories. Planets, films, vehicles, and starships follow the pattern cleanly (get_planets/get_planet_by_id, get_films/get_film_by_id, get_vehicles/get_vehicle_by_id, get_starships/get_starship_by_id). Two categories break it: get_people/get_person_by_id uses an irregular singular ("person," not "people" minus a suffix), and species is named get_species_list rather than get_species since the category name is already plural - both worth checking for when writing code against this server rather than assuming the pattern holds everywhere.

npx -y @johnpapa/mcp-starwars

A dedicated VS Code MCP JSON configuration format is also documented, listing the server under a servers block with an empty inputs array. Or install via Smithery CLI (npx -y @smithery/cli install @johnpapa/mcp-starwars --client claude), directly into VS Code with code --add-mcp, or from source (clone, npm install, npm run build, then test with the MCP Inspector). A VS Code settings.json entry looks like:

"mcp": {
  "servers": {
    "starwars": { "command": "npx", "args": ["-y", "@johnpapa/mcp-starwars"], "env": {} }
  }
},
"chat.mcp.discovery.enabled": true

Developers who want Star Wars reference data (characters, planets, films, species, vehicles, starships) available conversationally in an AI assistant, or who want a working reference implementation of pagination and caching patterns for wrapping a public REST API as an MCP server. Distributed under the MIT License, with installation badges documented for both VS Code and VS Code Insiders, covering both NPM-based and Docker-based install paths for editor integration.