How do I install Star Wars API & MCP Server (swapi.build)?

Copy the http config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Star Wars API & MCP Server (swapi.build) need an API key?

No required environment variable is listed on this record.

What transport does Star Wars API & MCP Server (swapi.build) use?

Star Wars API & MCP Server (swapi.build) is reached over HTTP.

When was Star Wars API & MCP Server (swapi.build) last checked?

Last checked 2026-11-12. Free Star Wars MCP server (SWAPI): people, films, planets, species, starships, vehicles. No API key.

Star Wars API & MCP Server (swapi.build) MCP server

Power your agent

Add this server

The publisher's own URL. Not a PlugMCP endpoint.

Add to Cursor Add in Claude Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Server URL

https://swapi.build/mcp

The Claude button above opens Claude with the name and URL filled in. You still confirm it there.

shClaude Code

1claude mcp add --transport http build.swapi-star-wars https://swapi.build/mcp

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "build.swapi-star-wars": {4      "command": "npx",5      "args": [6        "-y",7        "mcp-remote",8        "https://swapi.build/mcp"9      ]10    }11  }12}

claude_desktop_config.json

Remote · HTTPPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Remote

Transport: http
Version: 2.15.0
License

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

SWAPI.build

A free, open-source Star Wars API serving data about People, Films, Planets, Species, Starships, and Vehicles. Built with Quarkus and GraalVM for instant startup, minimal memory footprint, and out-of-the-box performance.

Inspired by the original SWAPI (created by Paul Hallett, maintained by Juriy Bura), this project was born out of the need for a Star Wars API that never goes offline. If you've ever had a live demo break because a third-party API went down, you know why this exists.

Quick Start

Prerequisites: Java 25 and Maven (or use the included Maven Wrapper).

cd swapi-app
./mvnw quarkus:dev

The API and frontend will be available at http://localhost:5432.

API Endpoints

Base path: /api

Resource	List All	By ID	Random	Search
People	`GET /api/people`	`GET /api/people/:id`	`GET /api/people/random`	`GET /api/people?search=name`
Films	`GET /api/films`	`GET /api/films/:id`	`GET /api/films/random`	`GET /api/films?search=title`
Planets	`GET /api/planets`	`GET /api/planets/:id`	`GET /api/planets/random`	`GET /api/planets?search=name`
Species	`GET /api/species`	`GET /api/species/:id`	`GET /api/species/random`	`GET /api/species?search=name`
Starships	`GET /api/starships`	`GET /api/starships/:id`	`GET /api/starships/random`	`GET /api/starships?search=name`
Vehicles	`GET /api/vehicles`	`GET /api/vehicles/:id`	`GET /api/vehicles/random`	`GET /api/vehicles?search=name`

Ids are the record ids from each entity's url field (for films, 1 = A New Hope). Successful responses return 200; unknown or non-numeric ids return 404.

GET /api/stats returns anonymous request counts per route (for example /api/people/{id} or /mcp) and per group (REST API, MCP, pages, SEO, other) for the last 24 hours (?period=24h, per hour), 7 days (default, per day; &granularity=hour for hourly) or 30 days (?period=30d, per day), each with the window before it for comparison, plus server response times per route and per group under performance (requests, mean, min, max, standard deviation and approximate p50/p95/p99 in milliseconds, network excluded). They are counted with no IP address or client details. The /stats page shows the same numbers with filters, a trend chart, a ranking and a Performance section.

All responses are JSON. Example:

curl http://localhost:5432/api/people/1

OpenAPI

The full API contract is served at /openapi.json (OpenAPI 3.x, generated from the code — always in sync). The documentation page renders from it, including a "try it" for every endpoint. Generate a client with, e.g.:

npx @openapitools/openapi-generator-cli generate -i https://swapi.build/openapi.json -g typescript-fetch

MCP Server

swapi.build is also a remote MCP server over Streamable HTTP. Any Streamable HTTP client works: the stateless 2026-07-28 revision sends self-contained requests, and earlier revisions negotiate a session through initialize — both are served on the same endpoint. The legacy HTTP+SSE transport (2024-11-05) is not supported. First-party, read-only, no authentication:

https://swapi.build/mcp

Full setup guides: swapi.build/docs/mcp

Tool	Arguments	Returns
`sw_list`	`resource`	All entities of a resource
`sw_get`	`resource`, `id`	One entity by id
`sw_random`	`resource`	A random entity
`sw_search`	`resource`, `query`	Name/title substring match

resource is one of PEOPLE, FILMS, PLANETS, SPECIES, STARSHIPS, VEHICLES. Ids are the record ids from each entity's url field (for FILMS, 1 = A New Hope).

Caching: Quarkiverse MCP Server 2.0.0 emits the required ttlMs: 0 and cacheScope: "public" fields on stateless discovery and tool-list responses. Zero TTL means immediately stale; no positive freshness period is configured. Its cache hints apply to discovery, list methods and resources/read, not tools/call. The Star Wars data here is exposed through tools, so tool-result caching is not enabled, including for sw_random. REST/edge caching is a separate mechanism.

claude mcp add --transport http swapi-build https://swapi.build/mcp

Or share via .mcp.json at the repo root:

{
  "mcpServers": {
    "swapi-build": { "type": "http", "url": "https://swapi.build/mcp" }
  }
}

Verify: claude mcp list → swapi-build ✔ Connected.

Settings → Connectors → Add custom connector → name swapi-build, URL https://swapi.build/mcp. No authentication needed. Verify in any chat via the + menu → Connectors.

codex mcp add swapi-build --url https://swapi.build/mcp

Or in ~/.codex/config.toml (shared by CLI, IDE extension and ChatGPT desktop):

[mcp_servers.swapi-build]
url = "https://swapi.build/mcp"

Verify: codex mcp list.

.vscode/mcp.json (top-level key is servers):

{
  "servers": {
    "swapi-build": { "type": "http", "url": "https://swapi.build/mcp" }
  }
}

Or Command Palette → MCP: Add Server. Verify via the Configure Tools button in Copilot Chat. On Business/Enterprise, the "MCP servers in Copilot" org policy must be enabled.

~/.bob/settings/mcp_settings.json (global) or .bob/mcp.json (project):

{
  "mcpServers": {
    "swapi-build": {
      "type": "streamable-http",
      "url": "https://swapi.build/mcp",
      "disabled": false
    }
  }
}

Or Bob panel → MCP tab → Edit Global MCP. Bob detects the tools automatically.

The server scales to zero when idle — if the very first connection attempt fails, retry once (the native binary starts in tens of milliseconds; the platform may take a bit longer to provision the container; subsequent calls are fast, whether your client is stateless or session-based).

WebMCP in the browser (experimental)

The website exposes sw_list, sw_get, sw_search and sw_random through WebMCP. Names and arguments match the remote MCP tools, including uppercase resource names. Each browser tool updates the visible explorer and returns complete records in a JSON result with ok, data, resource and path. The browser result envelope differs from the remote MCP transport.

Use a compatible browser with WebMCP enabled and the document.modelContext API. The setup and demonstration guide explains the inspector, example calls and cancellation behavior. When the API is unavailable, the site works normally. No model API key or AI runtime is embedded in the site. The JavaScript is bundled by Quinoa and runs in the browser, including when served by the Quarkus native executable.

Client examples

examples/java/langchain4j-mcp-client — ask questions in natural language; the tools come from the MCP server above, so the example defines none.
examples/java/quarkus-rest-client — call the REST API from Java with a typed client.

Project Structure

swapi-app/
  src/main/
    java/com/eldermoraes/     # Backend (Quarkus + Jakarta REST)
      film/                   # Film model, service, resource
      people/                 # People model, service, resource
      planet/                 # Planet model, service, resource
      specie/                 # Specie model, service, resource
      starship/               # Starship model, service, resource
      vehicle/                # Vehicle model, service, resource
      mcp/                    # MCP server tools (sw_list, sw_get, sw_random, sw_search)
      SWObject.java           # Base model class
      SWService.java          # Service interface
      ApiResource.java        # Root /api endpoint
      ApplicationPath.java    # Jakarta REST base path (/api)
    resources/
      data/                   # Static JSON data files
      application.properties  # Quarkus configuration
    webui/                    # Frontend (TypeScript + Vite)
      src/
        api.ts                # API client with request management
        main.ts               # SPA router
        pages/                # Page renderers (home, resource, docs, mcp, about, privacy, terms)
        json-highlight.ts     # JSON syntax highlighting for result panels
        style.css             # Site styles
        types.ts              # TypeScript interfaces for API resources
        constants.ts          # Shared resource metadata
        utils.ts              # Shared utilities (escapeHtml)
  src/test/
    java/com/eldermoraes/     # Regression suite (REST contracts, MCP tools, forwarded headers)

Each backend domain (film, people, planet, etc.) follows the same pattern:

Model (e.g., Film.java): POJO with @RegisterForReflection for native image support
Service (e.g., FilmService.java): loads data from JSON at startup, caches in memory
Resource (e.g., FilmResource.java): Jakarta REST controller with @RunOnVirtualThread

Build

cd swapi-app

# Development mode (live reload)
./mvnw quarkus:dev

# Production JAR
./mvnw package
java -jar target/quarkus-app/quarkus-run.jar

# Native executable (requires GraalVM or container build)
./mvnw package -Dnative
./mvnw package -Dnative -Dquarkus.native.container-build=true

The frontend is automatically built and bundled by Quinoa during the Maven build. No separate npm step is needed.

Deployment

The app runs as a native (GraalVM/Mandrel) executable on a self-hosted server on Oracle Cloud, managed by systemd behind Caddy (TLS via Let's Encrypt). DNS is managed on Cloudflare (DNS-only records pointing to the server). Publishing a GitHub Release runs .github/workflows/native-binary.yml: test suite, native build attached to the Release, a manual approval, then the install on the server over SSH and the production probes. The runbook is docs/DEPLOY.md.

Tech Stack

Runtime: Quarkus 3.33 on Java 25 with Virtual Threads
MCP server: Quarkiverse MCP Server — Streamable HTTP, stateless and session-based clients
Serialization: Jakarta REST + JSON-B
Native image: GraalVM via Mandrel builder
Frontend: TypeScript + Vite, served by Quinoa

Contributing

Pull requests are always welcome. Whether it's fixing a bug, improving the docs, or adding new features, jump in and help make the best Star Wars API in the galaxy even better.

Fork the repository
Create your feature branch (git checkout -b feature/my-change)
Make your changes (with tests) and run the suite: cd swapi-app && ./mvnw test
Commit and push
Open a Pull Request

Changelog and releases

Release history lives in CHANGELOG.md. Tagged releases are on the Releases page. The version served in /openapi.json (info.version) is always the latest released version. The release process itself is documented in docs/RELEASE.md.

Credits

Original SWAPI by Paul Hallett, maintained by Juriy Bura
Star Wars data from community-driven sources such as Wookieepedia
All Star Wars content and imagery are property of Lucasfilm Ltd. and Disney. This project is not affiliated with or endorsed by Lucasfilm or Disney.

License

Licensed under the Apache License 2.0. The website also publishes a Privacy Policy and Terms of Use.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Star Wars API & MCP Server (swapi.build)?

Does Star Wars API & MCP Server (swapi.build) need an API key?

What transport does Star Wars API & MCP Server (swapi.build) use?

When was Star Wars API & MCP Server (swapi.build) last checked?

Documentation

SWAPI.build

Quick Start

API Endpoints

OpenAPI

MCP Server

WebMCP in the browser (experimental)

Client examples

Project Structure

Build

Deployment

Tech Stack

Contributing

Changelog and releases

Credits

License