SWAPI MCP Server
olaekdahl/swapi-mcp-server
MCP server leve para consultas Star Wars via LLM
Ver no GitHubServidor Model Context Protocol que integra a Star Wars API como ferramentas MCP, permitindo que LLMs façam buscas de personagens, planetas e filmes da saga Star Wars. Implementado em TypeScript com suporte a transporte HTTP e stdio, inclui templates de prompts para análise e comparação de dados.
Instalação
npx convez-ai olaekdahl/swapi-mcp-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Integrar dados Star Wars em aplicações Claude/LLM
- Criar assistentes que analisam e comparam personagens Star Wars
- Demonstrar implementação de MCP servers com dados externos
- Explorar detalhes de planetas e filmes da franquia
Veredito

Exemplo bem estruturado de MCP server que demonstra integração com API REST externa. Útil para aprender padrões MCP e como expor dados terceirizados como ferramentas LLM, embora tenha escopo limitado ao domínio Star Wars.
README
A tradução para o português deste README ainda está na fila.
SWAPI MCP Server
A Model Context Protocol (MCP) server that wraps the Star Wars API (SWAPI) as MCP tools, allowing LLMs and clients to search for Star Wars characters, planets, and films.
Features
- MCP-compliant server using the official TypeScript SDK
- Exposes three tools:
search_character: Search for a Star Wars character by nameget_planet: Get detailed planet info by IDget_film: Get detailed film info by ID
- Exposes prompt templates:
analyze-charactercompare-charactersexplore-planet
- Exposes prompt compatibility tools for clients that only support tools:
prompt_analyze_characterprompt_compare_charactersprompt_explore_planet
- Supports HTTP (stateless, streamable) and optional stdio transport
- Includes unit, integration, and smoke tests
Code Structure
index.ts: Main entry point. Exports app/server builders, registers tools, and configures HTTP/stdio transports.test-client/: Example OpenAI client that demonstrates how to call the MCP server as a tool from an LLM.tests/: Unit tests, MCP HTTP integration tests, and smoke test script.
Tool Details
search_character
- Input:
{ name: string } - Description: Searches SWAPI for characters matching the given name.
- Returns: JSON-formatted list of matching characters.
get_planet
- Input:
{ id: string } - Description: Fetches detailed info for a planet by its SWAPI ID.
- Returns: JSON-formatted planet details.
get_film
- Input:
{ id: string } - Description: Fetches detailed info for a film by its SWAPI ID.
- Returns: JSON-formatted film details.
prompt_analyze_character
- Input:
{ characterName: string } - Description: Returns the analyze-character prompt text as tool output.
prompt_compare_characters
- Input:
{ character1: string, character2: string } - Description: Returns the compare-characters prompt text as tool output.
prompt_explore_planet
- Input:
{ planetId: string } - Description: Returns the explore-planet prompt text as tool output.
Prompt Templates
The server also exposes MCP prompt templates via prompt endpoints:
analyze-characterwith argumentcharacterNamecompare-characterswith argumentscharacter1,character2explore-planetwith argumentplanetId
Some chat surfaces only call MCP tools and do not directly invoke prompt endpoints. In those cases, use the prompt_* compatibility tools above.
How It Works
- Uses the @modelcontextprotocol/sdk to create an MCP server.
- Each tool is registered with an input schema (using zod) and an async handler that fetches data from SWAPI.
- The server can be accessed via HTTP POST requests to
/mcpor via stdio (for CLI clients).
Running the Server
Prerequisites
- Node.js v22 or newer
- npm
Install dependencies
npm install
Environment variables
PORT(default3000)ENABLE_HTTP(default1; set0to disable HTTP transport)ENABLE_STDIO(default0; set1to enable stdio transport)ALLOWED_ORIGINS(comma-separated CORS allowlist, defaults tohttp://localhost:3000,http://localhost:5173)
Run in HTTP mode (default)
npm run dev
- The server will listen on
http://localhost:3000/mcp(or the port set in thePORTenvironment variable).
Run in stdio mode (for CLI clients)
ENABLE_HTTP=0 ENABLE_STDIO=1 npm run dev
Run both transports
ENABLE_STDIO=1 npm run dev
Build and run compiled output
npm run build
npm start
Use From Another VS Code Instance (Same Machine)
This is the easiest way to use this MCP server from a second local VS Code window.
Option A (recommended): Register as a stdio MCP server
- Open a second VS Code instance.
- Open the workspace where you want to use this MCP server.
- Open Command Palette and run
MCP: Add Server. - Choose a local/command (stdio) server type.
- Use these values:
- Name:
swapi-local - Command:
node - Args:
--import,tsx,index.ts - Working directory:
/path/to/swapi-mcp-server - Environment variables:
ENABLE_HTTP=0ENABLE_STDIO=1
- Name:
- Save the MCP server configuration and reload the second VS Code window if prompted.
- In Chat, verify the server is available (for example via MCP server/tools list UI, then call a tool like
search_character).
If your VS Code MCP setup uses a JSON config file, this is the equivalent stdio config:
{
"servers": {
"swapi-local": {
"type": "stdio",
"command": "node",
"args": ["--import", "tsx", "index.ts"],
"cwd": "/path/to/swapi-mcp-server",
"env": {
"ENABLE_HTTP": "0",
"ENABLE_STDIO": "1"
}
}
}
}
Minimal server entry (using placeholder path):
{
"swapi-local": {
"type": "stdio",
"command": "node",
"args": ["--import", "tsx", "index.ts"],
"cwd": "/path/to/swapi-mcp-server",
"env": {
"ENABLE_HTTP": "0",
"ENABLE_STDIO": "1"
}
}
}
If you see Cannot find module .../dist/index.js in MCP logs, your server was launched with a command that expects a built artifact. Use the direct stdio command shown above, or run npm run build before using npm start.
Option B: Register as an HTTP MCP server
- In this repository, start the server in a terminal:
npm run dev
- In the second VS Code instance, add an MCP server using URL:
http://localhost:3000/mcp
- Save and test by calling a tool from Chat.
If your VS Code MCP setup uses JSON config, this is the equivalent HTTP config:
{
"servers": {
"swapi-http": {
"type": "http",
"url": "http://localhost:3000/mcp"
}
}
}
Example HTTP Request
List tools:
curl -X POST http://localhost:3000/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":0,"method":"tools/list","params":{}}'
Search for a character:
curl -N -X POST http://localhost:3000/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "search_character",
"arguments": { "name": "Luke" }
},
"id": 1
}'
Get a planet by ID:
curl -N -X POST http://localhost:3000/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "get_planet",
"arguments": { "id": "1" }
},
"id": 2
}'
Get a film by ID:
curl -N -X POST http://localhost:3000/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "get_film",
"arguments": { "id": "1" }
},
"id": 3
}'
Test Client: OpenAI + MCP Integration
The test-client/ directory contains an example script (swapi-client.ts) that demonstrates how to call the MCP server as a tool from an OpenAI LLM (e.g., GPT-4o-mini).
How it works
- Uses the OpenAI SDK and MCP tool integration.
- Registers the MCP server as a tool for the LLM.
- Sends a prompt/question to the LLM, which can call the MCP tools to answer.
Example: test-client/swapi-client.ts
// node --loader ts-node/esm ./swapi-client.ts
import 'dotenv/config';
import OpenAI from 'openai';
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY! });
const serverUrl = process.env.MCP_SERVER_URL ?? 'http://localhost:3000/mcp';
const model = process.env.OPENAI_MODEL ?? 'gpt-4o-mini';
const tools = [
{
type: "mcp" as const,
server_label: 'swapi',
server_url: serverUrl,
require_approval: 'never' as const,
},
];
const resp = await openai.responses.create({
model,
tools,
input: 'Where was Luke Skywalker born and how tall is he?',
});
console.log(resp.output_text);
Running the test client
- Install dependencies:
cd test-client npm install - Set your OpenAI API key in a
.envfile:OPENAI_API_KEY=sk-... - Start the MCP server (in the parent directory):
npm run dev
4. Run the test client:
```bash
cd test-client
npm run dev
- You should see the LLM's answer, which may include information fetched from the SWAPI MCP tools.
- To test with a remote tunnel, set
MCP_SERVER_URLintest-client/.env.
Testing
Run all tests:
npm test
Run focused suites:
npm run test:unit
npm run test:integration
npm run smoke
Run full verification:
npm run verify
Notes
- The server is stateless for HTTP requests (no session management).
- CORS is enabled with an allowlist and exposes the
mcp-session-idheader. - For more details on MCP, see the TypeScript SDK documentation.