Star Wars SWAPI MCP Server Integration Guide

Overview

This MCP (Model Context Protocol) server integration wraps the public SWAPI (Star Wars API) and exposes Star Wars resources as MCP tools. It provides a lightweight bridge that lets models or developer workflows query people, planets, starships, films, species, and vehicles in a standardized tool-like interface. That makes it easy to incorporate authoritative factual context from SWAPI into model responses, retrieval pipelines, or automated agents.

The server is useful for developers building conversational agents, tool-enabled language models, or any system that benefits from structured, machine-friendly access to SWAPI. It centralizes configuration (base URL, caching, rate limits), normalizes responses, and provides predictable endpoints for invoking resource lookups from downstream systems or LLM tool chains.

Features

• Exposes SWAPI endpoints as MCP-style tools (people, planets, starships, films, species, vehicles)
• Simple configuration for SWAPI base URL, port, and optional caching
• Tool invocation endpoints suitable for model-tooling or programmatic clients
• Example client usage with curl and JSON payloads
• Extensible: add custom resources, formatters, or additional proxies for other APIs

Installation / Configuration

Clone and run the server (Node.js example):

git clone https://github.com/johnpapa/mcp-starwars.git
cd mcp-starwars
npm install
# configure environment variables, then start
export SWAPI_BASE_URL="https://swapi.dev/api"
export PORT=3333
npm start

Example config file (config.json) — used by the server to map tools to SWAPI resources:

{
  "server": {
    "port": 3333
  },
  "swapi": {
    "baseUrl": "https://swapi.dev/api",
    "timeoutMs": 5000
  },
  "tools": {
    "people": { "resource": "people" },
    "planets": { "resource": "planets" },
    "starships": { "resource": "starships" },
    "films": { "resource": "films" },
    "species": { "resource": "species" },
    "vehicles": { "resource": "vehicles" }
  }
}

Environment variables override config.json settings for easy deployment.

Available Resources

The server proxies the standard SWAPI resource types. Each resource supports list and get-by-id operations.

The server also exposes a discovery endpoint listing available tools:

• GET /mcp/tools — returns registered tool metadata
• POST /mcp/invoke — invoke a tool with parameters

Example API Usage

List available tools:

curl http://localhost:3333/mcp/tools

Invoke the “people” tool by ID:

curl -X POST http://localhost:3333/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "people",
    "params": { "id": 1 }
  }'

Expected JSON response (trimmed):

{
  "tool": "people",
  "result": {
    "name": "Luke Skywalker",
    "height": "172",
    "mass": "77",
    "gender": "male",
    "homeworld": "https://swapi.dev/api/planets/1/",
    "films": [
      "https://swapi.dev/api/films/1/",
      "https://swapi.dev/api/films/2/"
    ]
  },
  "status": "ok"
}

Search/list resources (pagination follows SWAPI formats):

curl "http://localhost:3333/mcp/invoke" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "people",
    "params": { "search": "skywalker", "page": 1 }
  }'

Use Cases

• Agent tool integration: Register the MCP server’s tools with an LLM agent so the model can call “people” or “planets” during a conversation to fetch factual data and avoid hallucination.
  • Example: Agent receives prompt “Who is Luke Skywalker’s homeworld?” — the agent invokes tool “people” id=1, follows homeworld URL to “planets” tool, and returns the planet name reliably.
• Conversational knowledge augmentation: Use the server to enrich chat responses with up-to-date SWAPI data for quizzes, tutorials, or domain-specific demos.
• Testing and demos: Quickly mock a Star Wars knowledge source behind a standard MCP interface for training or evaluating tool-using models.
• Data pipelines: Periodically fetch and normalize SWAPI data for indexing, caching, or feeding into downstream analytics.

Extending and Troubleshooting

• Adding resources: Update config.json with a new tool mapping and restart the server. Implement formatters if you need specific output shapes.
• Caching: Add a caching layer (Redis or in-process) to reduce SWAPI calls and speed up repeat queries.
• Rate limits & retries: Configure request timeouts and retry policies in the server to handle SWAPI availability.
• Health checks: Verify the server is running with GET /health or your configured health endpoint.
• Logs: Check server logs for request/response traces when debugging failed invocations.

Repository and issues: https://github.com/johnpapa/mcp-starwars

This guide gives a practical baseline for running and integrating the MCP server with SWAPI. Use the discovery and invoke endpoints to wire these tools into model-driven workflows and agent architectures.