playbooks

home / mcp / star wars mcp server

Star Wars MCP Server

An application for study purposes to understand more about MCP with TypeScript using Star Wars API

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "glaucia86-swapi-mcp-server-app": {
      "command": "node",
      "args": [
        "CAMINHO_COMPLETO/swapi-mcp-server-app/build/index.js"
      ]
    }
  }
}

You have a TypeScript MCP server that exposes Star Wars data from SWAPI through Claude Desktop. It lets you ask about characters, planets, films, and more directly from Claude, giving you quick, structured answers without leaving your chat flow.

How to use

Interact with the MCP server through your MCP client (Claude Desktop or compatible tool). You can ask questions about Star Wars characters, planets, and films, or request details by character ID. The server exposes a set of tools to perform searches and retrieve specific data, providing fast, contextual responses inside Claude.

How to install

Prerequisites you need before installing: Node.js version 18 or higher, Claude Desktop installed, and npm or yarn available on your system.

1. Clone the project repository.

git clone https://github.com/glaucia86/swapi-mcp-server-app.git

2. Change into the project directory and install dependencies.

cd swapi-mcp-server-app
npm install

3. Build the TypeScript project so the server is ready to run.

npm run build

4. Configure Claude Desktop to connect to the MCP server. Add the following MCP configuration so Claude can start the server when you load Claude.

{
  "mcpServers": {
    "swapi-mcp-server": {
      "command": "node",
      "args": ["CAMINHO_COMPLETO/swapi-mcp-server-app/build/index.js"]
    }
  }
}

Replace CAMINHO_COMPLETO with the absolute path to your project folder. Finally, restart Claude Desktop completely to apply the new MCP server configuration.

5. Verification. Claude Desktop will start the MCP server automatically. You can verify the setup by asking Claude questions about Star Wars and confirming you receive responses powered by the SWAPI MCP server.

Troubleshooting

If the server does not appear in Claude Desktop, check these items in order:

  • Ensure the path in the configuration is correct
  • Confirm the build output exists at build/index.js
  • Fully restart Claude Desktop
  • Inspect logs at %APPDATA%\Claude\logs\mcp.log

If there are compilation errors, try reinstalling dependencies and rebuilding each time, ensuring you are using a Node.js version compatible with the project.

Testing with the Inspector

To test and debug the MCP server, run the inspector tool. It opens in your browser and lets you test tools, review available resources, debug connection issues, and view real-time logs.

npm run inspector

Examples of questions

You can ask Claude for data like:

  • Search for a character by name, e.g., Luke Skywalker
  • Find a planet by name, e.g., Tatooine
  • Look up a film by title, e.g., The Empire Strikes Back
  • Request detailed data for a character by ID, e.g., 1
  • List all Star Wars films ordered by episode

Available tools

search_characters

Search Star Wars characters by name and return matching results.

search_planets

Search Star Wars planets by name and return matching results.

search_films

Search Star Wars films by title and return matching results.

get_character_by_id

Retrieve detailed information about a character using their ID.

all_films

List all Star Wars films ordered by episode.