Star Wars API (SWAPI) as a remote MCP server: films, people, planets, species, starships, vehicles.
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.
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.
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.
All responses are JSON. Example:
curl http://localhost:5432/api/people/1
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
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).
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).
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.swapi-app/
Dockerfile.vercel # Native container image used by Vercel deploys
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:
Film.java): POJO with @RegisterForReflection for native image supportFilmService.java): loads data from JSON at startup, caches in memoryFilmResource.java): Jakarta REST controller with @RunOnVirtualThreadcd 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.
The app runs on Vercel as a native (GraalVM/Mandrel) container image, built from swapi-app/Dockerfile.vercel. DNS is managed on Cloudflare (DNS-only records pointing to Vercel). Deploys are done with npx vercel deploy --prod from the swapi-app/ directory.
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.
git checkout -b feature/my-change)cd swapi-app && ./mvnw testRelease 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.
Licensed under the Apache License 2.0. The website also publishes a Privacy Policy and Terms of Use.
This listing does not have a supported local package template. Use the maintainer’s documentation for its hosted endpoint, authentication, and client-specific setup. No install command has been inferred.