MCP REST Server

Un servidor para interactuar con APIs REST, con soporte de autenticación y documentación Swagger.

Documentación

MCP REST Server

Un servidor de Protocolo de Contexto de Modelo (MCP) que ofrece funcionalidad de cliente de API REST con soporte de autenticación e integración con documentación de Swagger.

Características

Múltiples métodos de autenticación: Soporte para autenticación basada en token y basada en inicio de sesión
Integración con Swagger: Descubrimiento automático de endpoints y documentación a partir de especificaciones OpenAPI/Swagger
Gestión automática de tokens: Maneja la renovación de tokens y la reautenticación
Métodos HTTP completos: Soporte para solicitudes GET, POST, PUT, DELETE y PATCH
Manejo de errores: Manejo robusto de errores con lógica de reintentos
Compatible con MCP: Totalmente compatible con el Protocolo de Contexto de Modelo

Instalación

npm install
npm run build

Desarrollo

npm run dev

Configuración

El servidor admite dos métodos de autenticación:

Autenticación por token

{
  "baseUrl": "https://api.example.com",
  "swaggerUrl": "https://api.example.com/swagger.json",
  "auth": {
    "type": "token",
    "token": "your-api-token-here"
  },
  "timeout": 30000,
  "retries": 3
}

Autenticación por inicio de sesión

{
  "baseUrl": "https://api.example.com",
  "swaggerUrl": "https://api.example.com/swagger.json",
  "auth": {
    "type": "login",
    "username": "your-username",
    "password": "your-password",
    "loginEndpoint": "/auth/login",
    "tokenField": "access_token"
  },
  "timeout": 30000,
  "retries": 3
}

Herramientas disponibles

1. configure_rest_client

Configura el cliente REST con autenticación y detalles de la API.

Parámetros:

baseUrl (obligatorio): URL base para la API REST
auth (obligatorio): Configuración de autenticación (token o inicio de sesión)
swaggerUrl (opcional): URL de la documentación Swagger/OpenAPI
timeout (opcional): Tiempo de espera de la solicitud en milisegundos (predeterminado: 30000)
retries (opcional): Número de reintentos para solicitudes fallidas (predeterminado: 3)

2. http_request

Realiza solicitudes HTTP a la API configurada.

Parámetros:

method (obligatorio): Método HTTP (GET, POST, PUT, DELETE, PATCH)
path (obligatorio): Ruta del endpoint de la API
params (opcional): Parámetros de consulta o parámetros del cuerpo de la solicitud
body (opcional): Cuerpo de la solicitud para solicitudes POST, PUT, PATCH
headers (opcional): Cabeceras adicionales

3. get_swagger_documentation

Obtiene la lista completa de endpoints disponibles desde la documentación de Swagger.

4. search_endpoints

Busca endpoints en la documentación de Swagger.

Parámetros:

query (obligatorio): Consulta de búsqueda para encontrar endpoints coincidentes

5. get_endpoint_info

Obtiene información detallada acerca de un endpoint específico.

Parámetros:

path (obligatorio): Ruta del endpoint
method (obligatorio): Método HTTP

6. check_authentication

Comprueba si el cliente está actualmente autenticado.

7. logout

Cierra la sesión y limpia el estado de autenticación.

Ejemplos de uso

Configuración básica

Configura el cliente:

{
  "baseUrl": "https://jsonplaceholder.typicode.com",
  "auth": {
    "type": "token",
    "token": "dummy-token"
  }
}

Realiza una solicitud GET:

{
  "method": "GET",
  "path": "/posts/1"
}

Realiza una solicitud POST:

{
  "method": "POST",
  "path": "/posts",
  "body": {
    "title": "New Post",
    "body": "Post content",
    "userId": 1
  }
}

Con documentación Swagger

{
  "baseUrl": "https://petstore.swagger.io/v2",
  "swaggerUrl": "https://petstore.swagger.io/v2/swagger.json",
  "auth": {
    "type": "token",
    "token": "your-api-key"
  }
}

Después puedes:

Buscar endpoints: search_endpoints con la consulta "pet"
Obtener información del endpoint: get_endpoint_info con la ruta "/pet" y el método "POST"
Ver toda la documentación: get_swagger_documentation

Flujo de autenticación

Autenticación por token

El token se almacena y se usa inmediatamente
Se añade a las solicitudes como Authorization: Bearer <token>
Si se recibe un 401, no se realiza reintento automático (se asume que el token no es válido)

Autenticación por inicio de sesión

Realiza una solicitud de inicio de sesión al endpoint especificado
Extrae el token de la respuesta usando tokenField
Almacena el token en memoria
Añade el token a las solicitudes posteriores
Si se recibe un 401, se reautentica automáticamente y reintenta

Manejo de errores

Errores de red: Reintento automático con retroceso exponencial
Errores de autenticación: Reautenticación automática para la autenticación basada en inicio de sesión
Errores de validación: Mensajes de error claros con detalles
Errores de API: Reenvío del estado HTTP y del mensaje de error

Desarrollo

Estructura del proyecto

src/
├── types.ts          # TypeScript type definitions
├── auth.ts           # Authentication manager
├── swagger.ts        # Swagger documentation parser
├── rest-client.ts    # REST client implementation
└── index.ts          # MCP server implementation

Compilación

npm run build

Ejecución

npm start

Configuración del cliente MCP

El servidor MCP REST ahora soporta configuración automática a través de varios métodos, eliminando la necesidad de configurar APIs manualmente para cada proyecto.

Métodos de configuración (en orden de prioridad)

Argumentos de línea de comandos (mayor prioridad)
Variables de entorno
Archivo de configuración
Configuración manual (a través de las herramientas MCP - menor prioridad)

Configuración de Cursor

Opción 1: Configuración automática con variables de entorno (recomendada)

{
  "mcpServers": {
    "mcp-rest-github": {
      "command": "node",
      "args": ["/path/to/your/mcp-rest/dist/index.js"],
      "env": {
        "MCP_REST_BASE_URL": "https://api.github.com",
        "MCP_REST_AUTH_TYPE": "token",
        "MCP_REST_TOKEN": "your-github-token-here",
        "MCP_REST_SWAGGER_URL": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json"
      }
    },
    "mcp-rest-petstore": {
      "command": "node",
      "args": ["/path/to/your/mcp-rest/dist/index.js"],
      "env": {
        "MCP_REST_BASE_URL": "https://petstore.swagger.io/v2",
        "MCP_REST_AUTH_TYPE": "token",
        "MCP_REST_TOKEN": "your-api-key",
        "MCP_REST_SWAGGER_URL": "https://petstore.swagger.io/v2/swagger.json"
      }
    }
  }
}

Opción 2: Configuración automática con archivos de configuración

{
  "mcpServers": {
    "mcp-rest-github": {
      "command": "node",
      "args": ["/path/to/your/mcp-rest/dist/index.js", "--config", "/path/to/your/mcp-rest/examples/github-api.json"]
    },
    "mcp-rest-petstore": {
      "command": "node",
      "args": ["/path/to/your/mcp-rest/dist/index.js", "--config", "/path/to/your/mcp-rest/examples/petstore.json"]
    }
  }
}

Opción 3: Configuración automática con argumentos de línea de comandos

{
  "mcpServers": {
    "mcp-rest-github": {
      "command": "node",
      "args": [
        "/path/to/your/mcp-rest/dist/index.js",
        "--base-url", "https://api.github.com",
        "--auth-type", "token",
        "--token", "your-github-token-here",
        "--swagger-url", "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json"
      ]
    }
  }
}

Configuración de Claude Desktop

Ubicación:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Usa las mismas opciones de configuración que Cursor arriba.

Ejemplos de configuración

El proyecto incluye varias configuraciones de ejemplo en el directorio examples/:

examples/github-api.json - Configuración de la API de GitHub
examples/petstore.json - Configuración de la API de Swagger Petstore
examples/jsonplaceholder.json - Configuración de la API de JSONPlaceholder

Variables de entorno

Variable	Descripción
`MCP_REST_BASE_URL`	URL base para la API REST (obligatorio)
`MCP_REST_AUTH_TYPE`	Tipo de autenticación: 'token' o 'login' (obligatorio)
`MCP_REST_TOKEN`	Token de API (obligatorio para la autenticación por token)
`MCP_REST_USERNAME`	Nombre de usuario (obligatorio para la autenticación por inicio de sesión)
`MCP_REST_PASSWORD`	Contraseña (obligatorio para la autenticación por inicio de sesión)
`MCP_REST_LOGIN_ENDPOINT`	Ruta del endpoint de inicio de sesión (obligatorio para la autenticación por inicio de sesión)
`MCP_REST_TOKEN_FIELD`	Nombre del campo del token en la respuesta de inicio de sesión (predeterminado: access_token)
`MCP_REST_SWAGGER_URL`	URL de la documentación Swagger/OpenAPI
`MCP_REST_TIMEOUT`	Tiempo de espera de la solicitud en milisegundos (predeterminado: 30000)
`MCP_REST_RETRIES`	Número de reintentos para solicitudes fallidas (predeterminado: 3)
`MCP_REST_CONFIG_FILE`	Ruta al archivo de configuración JSON

Nota: Reemplaza /path/to/your/mcp-rest/ con la ruta real a tu directorio del servidor MCP REST.

Uso en Claude/Cursor

Con configuración automática (recomendado)

Si has configurado el servidor con configuración automática (variables de entorno, argumentos de CLI o archivo de configuración), el servidor estará listo para usarse inmediatamente:

Make a GET request to /posts/1
Show me all available endpoints
Search for endpoints related to "user"

Con configuración manual

Si no has proporcionado configuración automática, aún puedes configurar el cliente manualmente:

Configura el cliente primero:

Please configure the REST client with:
- Base URL: https://api.example.com
- Authentication: token
- Token: your-api-token-here
- Swagger URL: https://api.example.com/swagger.json

Después haz solicitudes a la API:

Make a GET request to /users/123

Probar la configuración

Puedes probar tu configuración antes de usarla en Claude/Cursor:

# Test with config file
node dist/index.js --config examples/jsonplaceholder.json

# Test with CLI arguments
node dist/index.js --base-url https://api.github.com --auth-type token --token your-token

# Test with environment variables
MCP_REST_BASE_URL=https://httpbin.org MCP_REST_AUTH_TYPE=token MCP_REST_TOKEN=test node dist/index.js

Si ves "✅ Cliente REST configurado automáticamente para [URL]", la configuración está funcionando correctamente.

Licencia

MIT