Star Wars API & MCP server (swapi.build)

Gets one Star Wars entity by numeric record id and returns it as a JSON object. Take the id from the end of an entity's url field (from sw_search, sw_list or a relation URL). Ids are record ids, not episode numbers: FILMS id 1 is A New Hope (Episode IV). An unknown id returns a tool error, e.g. 'No films found with id 99'. Pass expand to get related records in the same call, e.g. ["homeworld", "species"]; name only the relations you need; * on a film can pass 50 KB.

{
  "type": "object",
  "properties": {
    "expand": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional. Relations to embed, one level deep, under a final \"expanded\" key: PEOPLE homeworld, films, species, vehicles, starships; FILMS characters, planets, starships, vehicles, species; PLANETS residents, films; SPECIES homeworld, people, films; STARSHIPS and VEHICLES pilots, films; or [\"*\"] alone for all. Up to 8 names; an unknown name returns a tool error."
    },
    "id": {
      "type": "integer",
      "description": "Numeric record id: the last segment of the entity's url field (1 in .../api/people/1)."
    },
    "resource": {
      "type": "string",
      "enum": [
        "PEOPLE",
        "FILMS",
        "PLANETS",
        "SPECIES",
        "STARSHIPS",
        "VEHICLES"
      ],
      "description": "Resource type: PEOPLE, FILMS, PLANETS, SPECIES, STARSHIPS or VEHICLES. Any other value returns a tool error."
    }
  },
  "required": [
    "resource",
    "id"
  ]
}

Lists every entity of one Star Wars resource type as a JSON array (Episodes I-VI data). Responses are large (all 82 PEOPLE, about 38 KB); to find a single entity, prefer sw_search, then sw_get; for a compact index pass fields, e.g. ["name"] (about 5 KB).

{
  "type": "object",
  "properties": {
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional. Field names to keep in each entity (url is always kept), e.g. [\"name\"] (FILMS: [\"title\"]). Up to 24 names; an unknown name returns a tool error listing the valid ones. Omit for full entities."
    },
    "resource": {
      "type": "string",
      "enum": [
        "PEOPLE",
        "FILMS",
        "PLANETS",
        "SPECIES",
        "STARSHIPS",
        "VEHICLES"
      ],
      "description": "Resource type: PEOPLE, FILMS, PLANETS, SPECIES, STARSHIPS or VEHICLES. Any other value returns a tool error."
    }
  },
  "required": [
    "resource"
  ]
}

Returns one random Star Wars entity of the given resource type as a JSON object. Each call can return a different entity, so it is not idempotent. Useful for demos and quizzes; to fetch a specific entity use sw_search or sw_get.

{
  "type": "object",
  "properties": {
    "resource": {
      "type": "string",
      "enum": [
        "PEOPLE",
        "FILMS",
        "PLANETS",
        "SPECIES",
        "STARSHIPS",
        "VEHICLES"
      ],
      "description": "Resource type: PEOPLE, FILMS, PLANETS, SPECIES, STARSHIPS or VEHICLES. Any other value returns a tool error."
    }
  },
  "required": [
    "resource"
  ]
}

Start here. Finds Star Wars entities by name (title for FILMS) with a case-insensitive substring match: 'sky' finds Luke, Anakin and Shmi Skywalker. Returns a JSON array of full entities; an empty array [] means no match; pass fields to shorten each entity. The id to pass to sw_get is the last segment of each entity's url field. Data covers Episodes I-VI only.

{
  "type": "object",
  "properties": {
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional. Field names to keep in each entity (url is always kept), e.g. [\"name\"] (FILMS: [\"title\"]). Up to 24 names; an unknown name returns a tool error listing the valid ones. Omit for full entities."
    },
    "query": {
      "type": "string",
      "description": "Name or title fragment, case-insensitive (e.g. 'falcon', 'hope')."
    },
    "resource": {
      "type": "string",
      "enum": [
        "PEOPLE",
        "FILMS",
        "PLANETS",
        "SPECIES",
        "STARSHIPS",
        "VEHICLES"
      ],
      "description": "Resource type: PEOPLE, FILMS, PLANETS, SPECIES, STARSHIPS or VEHICLES. Any other value returns a tool error."
    }
  },
  "required": [
    "resource",
    "query"
  ]
}