<div align="center">

Star Wars MCP Server

Features • Tools • Setup • Configuring an MCP Host

</div>

MCP Server for the SWAPI Star Wars API. The main goal of the project is to show how an MCP server can be used to interact with APIs.

Note: All data used by this MCP server is fetched from the SWAPI documentation](https://swapi.dev).

<a name="features"></a>

🔧 Features

• List Star Wars Characters: Get character data with optional search filters and automatic pagination
• List Planets, Films, Species, Vehicles, and Starships: Access all Star Wars entity collections with search capabilities
• Fetch Entity Details by ID: Get detailed information about specific characters, planets, films, species, vehicles, or starships
• Automatic Pagination: Seamlessly retrieve all pages of data with a single API call
• Built-in Caching: Optimize performance with intelligent API response caching
• Cache Management: Clear cache and view cache statistics to monitor performance
• Tool-based MCP Integration: Register this server with Model Context Protocol (MCP) tools (VS Code, Claude, etc.)

<a name="tools"></a>

🧰 Tools

1. get_people 🧑‍🤝‍🧑

• Description: List Star Wars characters with automatic pagination and optional search
• Inputs:
  • page (optional number): The page number to retrieve (defaults to 1)
  • search (optional string): Name or partial name to search for
  • fetchAllPages (optional boolean): Whether to automatically fetch all pages of results (defaults to true)
• Returns: Collection of Star Wars character data including name, physical attributes, homeworld, and related entities

2. get_person_by_id 👤

• Description: Get details about a specific Star Wars character by ID
• Input:
  • id (string or number): The unique identifier of the character
• Returns: Complete data for the requested character including name, physical attributes, homeworld, and related entities

3. get_planets 🪐

• Description: List Star Wars planets with automatic pagination and optional search
• Inputs:
  • page (optional number): The page number to retrieve (defaults to 1)
  • search (optional string): Planet name or partial name to search for
  • fetchAllPages (optional boolean): Whether to automatically fetch all pages of results (defaults to true)
• Returns: Collection of Star Wars planet data including climate, terrain, population, and related entities

4. get_planet_by_id 🌍

• Description: Get details about a specific Star Wars planet by ID
• Input:
  • id (string or number): The unique identifier of the planet
• Returns: Complete data for the requested planet including climate, terrain, population, and related entities

5. get_films 🎬

• Description: List Star Wars films with automatic pagination and optional search
• Inputs:
  • page (optional number): The page number to retrieve (defaults to 1)
  • search (optional string): Film title or partial title to search for
  • fetchAllPages (optional boolean): Whether to automatically fetch all pages of results (defaults to true)
• Returns: Collection of Star Wars film data including title, episode ID, director, and related entities

6. get_film_by_id 📽️

• Description: Get details about a specific Star Wars film by ID
• Input:
  • id (string or number): The unique identifier of the film
• Returns: Complete data for the requested film including title, episode ID, director, and related entities

7. get_species_list 👽

• Description: List Star Wars species with automatic pagination and optional search
• Inputs:
  • page (optional number): The page number to retrieve (defaults to 1)
  • search (optional string): Species name or partial name to search for
  • fetchAllPages (optional boolean): Whether to automatically fetch all pages of results (defaults to true)
• Returns: Collection of Star Wars species data including classification, physical attributes, and related entities

8. get_species_by_id 🧬

• Description: Get details about a specific Star Wars species by ID
• Input:
  • id (string or number): The unique identifier of the species
• Returns: Complete data for the requested species including classification, physical attributes, and related entities

9. get_vehicles 🚗

• Description: List Star Wars vehicles with automatic pagination and optional search
• Inputs:
  • page (optional number): The page number to retrieve (defaults to 1)
  • search (optional string): Vehicle name or partial name to search for
  • fetchAllPages (optional boolean): Whether to automatically fetch all pages of results (defaults to true)
• Returns: Collection of Star Wars vehicle data including model, manufacturer, and specifications

10. get_vehicle_by_id 🚙

• Description: Get details about a specific Star Wars vehicle by ID
• Input:
  • id (string or number): The unique identifier of the vehicle
• Returns: Complete data for the requested vehicle including model, manufacturer, and specifications

11. get_starships 🚀

• Description: List Star Wars starships with automatic pagination and optional search
• Inputs:
  • page (optional number): The page number to retrieve (defaults to 1)
  • search (optional string): Starship name or partial name to search for
  • fetchAllPages (optional boolean): Whether to automatically fetch all pages of results (defaults to true)
• Returns: Collection of Star Wars starship data including model, manufacturer, and specifications

12. get_starship_by_id 🛸

• Description: Get details about a specific Star Wars starship by ID
• Input:
  • id (string or number): The unique identifier of the starship
• Returns: Complete data for the requested starship including model, manufacturer, and specifications

13. clear_cache 🧹

• Description: Clear the Star Wars API cache (partially or completely)
• Input:
  • endpoint (optional string): Specific endpoint to clear from cache. Leave empty to clear all.
• Returns: Confirmation message indicating which cache was cleared

14. get_cache_stats 📊

• Description: Get statistics about the Star Wars API cache usage
• Inputs: None
• Returns: Cache hit/miss statistics, size, and performance metrics

<a name="setup"></a>

🛠️ Setup

Quick Installation in VS Code

For the quickest installation, click on one of the VS Code installation buttons at the top of this README.

Manual Installation in VS Code

Using the Command Line

You can install the Star Wars MCP server manually using the following commands:

For VS Code Stable:

code --add-mcp '{"name":"starwars","command":"npx","args":["-y","@johnpapa/mcp-starwars"],"env":{}}'

For VS Code Insiders:

code-insiders --add-mcp '{"name":"starwars","command":"npx","args":["-y","@johnpapa/mcp-starwars"],"env":{}}'

Using VS Code Settings

1. Open VS Code Settings (File > Preferences > Settings)
2. Click on the "Open Settings (JSON)" icon in the top right corner
3. Add the following configuration to your settings.json file:

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

Installing via Smithery

To install Star Wars MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @johnpapa/mcp-starwars --client claude

Run the MCP Server Locally with MCP Inspector

If you'd like to run MCP Inspector locally to test the server, follow these steps:

1. Clone this repository:

   git clone https://github.com/johnpapa/-mcp-starwars
   

2. Install the required dependencies and build the project.

   npm install
   npm run build
   

3. (Optional) To try out the server using MCP Inspector run the following command:

   # Start the MCP Inspector
   npx @modelcontextprotocol/inspector node build/index.js
   

   Visit the MCP Inspector URL shown in the console in your browser. Change Arguments to dist/index.js and select Connect. Select List Tools to see the available tools.

<a name="configuring-an-mcp-host"></a>

Running the MCP Server hosted in GitHub Copilot with VS Code Insiders

Note: If you already have the MCP server enabled with Claude Desktop, add chat.mcp.discovery.enabled: true in your VS Code settings and it will discover existing MCP server lists.

If you want to associate the MCP server with a specific repo, create a .vscode/mcp.json file with this content:

{
  "inputs": [],
  "servers": {
    "mcp-starwars": {
      "command": "npx",
      // "command": "node",
      "args": [
        "-y",
        "@johnpapa/mcp-starwars"
        // "_git/mcp-starwars/dist/index.js"
      ],
      "env": {}
    }
  }
}

If you want to associate the MCP server with all repos, add the following to your VS Code User Settings JSON:

"mcp": {
  "servers": {
    "mcp-starwars": {
      "command": "npx",
      // "command": "node",
      "args": [
        "-y",
        "@johnpapa/mcp-starwars"
        // "/Users/papa/_git/mcp-starwars/dist/index.js"
        // "_git/mcp-starwars/dist/index.js"
      ],
      "env": {}
    }
  }
}
"chat.mcp.discovery.enabled": true,

Using Tools in GitHub Copilot

1. Now that the mcp server is discoverable, open GitHub Copilot and select the Agent mode (not Chat or Edits).

2. Select the "refresh" button in the Copilot chat text field to refresh the server list.

3. Select the "🛠️" button to see all the possible tools, including the ones from this repo.

4. Put a question in the chat that would naturally invoke one of the tools, for example:

   How do I set my VS Code accent colors?
   

   Note: If you see "Sorry, the response was filtered by the Responsible AI Service. Please rephrase your prompt and try again.", try running it again or rephrasing the prompt.