Star Wars MCP Server

What is Star Wars MCP Server about?

The server acts as a bridge between Model Context Protocol clients and the public SWAPI Star Wars API. It wraps the REST endpoints into a set of well‑defined tools, allowing AI agents or code assistants to retrieve Star Wars data without handling HTTP requests directly.

How to use Star Wars MCP Server?

Install the server in VS Code (or any MCP‑compatible environment) using the provided badge buttons or via the command line:
```
code --add-mcp '{"name":"starwars","command":"npx","args":["-y","@johnpapa/mcp-starwars"],"env":{}}'
```

Configure the server in your VS Code settings.json if you prefer a persistent setup:

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

Invoke tools from any MCP‑aware client (e.g., Claude Desktop, GitHub Copilot Agent) by selecting the desired operation such as get_people, get_planet_by_id, or clear_cache.

Key features of Star Wars MCP Server

List and search all main Star Wars entities (characters, planets, films, species, vehicles, starships).
Automatic pagination with an optional fetchAllPages flag.
Built‑in response caching plus commands to clear cache and view cache statistics.
Simple VS Code integration via badges, command‑line, or settings.
Fully typed TypeScript implementation for reliable tool contracts.

Use cases of Star Wars MCP Server

Enrich AI chat assistants with factual Star Wars data without writing custom HTTP logic.
Prototype educational bots that answer Star Wars trivia.
Demonstrate MCP server creation patterns for internal APIs.
Rapidly prototype UI components that need Star Wars data during demos or hackathons.

FAQ from the Star Wars MCP Server

Q: Do I need an API key for SWAPI? A: No. SWAPI is a public, unauthenticated API.

Q: Can I limit pagination to a single page? A: Yes. Set fetchAllPages to false and specify the page number.

Q: How do I reset the cache? A: Use the clear_cache tool; specify an endpoint to clear selectively or leave it empty to purge everything.

Q: Is there support for other languages or runtimes? A: The server is written in TypeScript/Node.js and runs wherever an MCP client can execute npx commands.

Q: How do I view cache metrics? A: Call the get_cache_stats tool which returns hit/miss counts, size, and performance data.

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

Open VS Code Settings (File > Preferences > Settings)
Click on the "Open Settings (JSON)" icon in the top right corner
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:

Clone this repository:

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

Install the required dependencies and build the project.
```
npm install
npm run build
```
(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

Now that the mcp server is discoverable, open GitHub Copilot and select the Agent mode (not Chat or Edits).
Select the "refresh" button in the Copilot chat text field to refresh the server list.
Select the "🛠️" button to see all the possible tools, including the ones from this repo.
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.

Star Wars MCP Server