Star Wars

What is mcp-starwars?

mcp-starwars is an MCP (Model Context Protocol) server designed to interact with the SWAPI Star Wars API. Its primary goal is to showcase how an MCP server can be effectively used to communicate with and retrieve data from external APIs. All data utilized by this MCP server is sourced directly from the SWAPI documentation.

How to use mcp-starwars?

mcp-starwars can be installed and used in several ways:

• Quick Installation in VS Code: Use the provided VS Code installation buttons in the README.
• Manual Installation in VS Code: Install via command line (for VS Code Stable or Insiders) or by adding configuration to your settings.json file.
• Installing via Smithery: Use the npx @smithery/cli install @johnpapa/mcp-starwars --client claude command.
• Running Locally with MCP Inspector: Clone the repository, install dependencies, build the project, and then run npx @modelcontextprotocol/inspector node build/index.js.
• Running Hosted in GitHub Copilot with VS Code Insiders: Configure .vscode/mcp.json for a specific repository or add settings to your VS Code User Settings JSON for all repositories. After setup, refresh the server list in GitHub Copilot and use the "🛠️" button to see available tools. You can then ask questions that invoke these tools.

Key Features of mcp-starwars

• List Star Wars Characters: Retrieve character data with optional search and automatic pagination.
• List Planets, Films, Species, Vehicles, and Starships: Access various Star Wars entity collections with search capabilities.
• Fetch Entity Details by ID: Get detailed information for 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 the cache and view cache statistics.
• Tool-based MCP Integration: Register the server with MCP tools like VS Code and Claude.

Use Cases of mcp-starwars

• Demonstrating MCP Server Capabilities: Serves as a practical example of how MCP servers can interact with external APIs.
• Developing Applications with Star Wars Data: Provides a structured way to access and utilize Star Wars data in applications.
• Learning and Experimenting with MCP: Offers a hands-on project for understanding and working with the Model Context Protocol.
• Integrating Star Wars Data into AI/Chatbots: Enables AI tools like GitHub Copilot and Claude to access and respond with Star Wars information.

FAQ from mcp-starwars

Q: What is the main goal of this project? A: The main goal is to demonstrate how an MCP server can be used to interact with APIs, specifically the SWAPI Star Wars API.

Q: Where does the data for this MCP server come from? A: All data used by this MCP server is fetched directly from the SWAPI documentation (https://swapi.dev).

Q: How can I clear the cache? A: You can use the clear_cache tool, optionally specifying an endpoint to clear or leaving it empty to clear all.

Q: How can I see cache statistics? A: Use the get_cache_stats tool to view cache hit/miss statistics, size, and performance metrics.

Q: Can I use this with GitHub Copilot? A: Yes, you can configure the MCP server to be discoverable by GitHub Copilot in VS Code Insiders and then use its tools within Copilot Agent mode.

Features • Tools • Setup • Configuring an MCP Host

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).

🔧 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.)

🧰 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

🛠️ 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.

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.