sparkit-mcp

Name: mcp-sparkit
Author: SPARKIT-science

Servidor MCP para SPARKIT — llama al agente de investigación científica desde Claude Desktop, Cursor, Claude Code o cualquier otro cliente compatible con MCP.

Se exponen dos herramientas:

research — envía una pregunta científica. SPARKIT busca en la literatura, lee los artículos relevantes y devuelve un informe en Markdown con citas. Se bloquea hasta que finaliza el trabajo (4 minutos por defecto) y devuelve el informe completo en línea.
get_job_status — recupera un trabajo enviado previamente mediante su ID. Útil cuando research devuelve un resultado antes de que el trabajo haya finalizado, o para revisar un informe anterior.

Instalación

uv tool install sparkit-mcp

O con pip:

pip install sparkit-mcp

Cualquiera de las dos opciones instala un script de consola sparkit-mcp. (Pre-lanzamiento: instalar directamente desde GitHub con uv tool install "git+https://github.com/SPARKIT-science/sparkit-mcp.git" hasta que llegue el primer lanzamiento en PyPI).

Obtener una clave API

Regístrate en https://app.sparkit.science/signup (la opción "Try-it" cuesta 10 $ por 5 consultas; las suscripciones comienzan en 50 $/mes).
Visita https://app.sparkit.science/keys y crea una clave.
Copia la clave: solo se muestra una vez.

Configurar tu cliente MCP

Claude Desktop

Edita claude_desktop_config.json:

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

Añade:

{
  "mcpServers": {
    "sparkit": {
      "command": "sparkit-mcp",
      "env": {
        "SPARKIT_API_KEY": "sk_sparkit_..."
      }
    }
  }
}

Reinicia Claude Desktop. Deberías ver aparecer sparkit en el icono de herramientas junto a la entrada de chat.

Si sparkit-mcp no está en el PATH de Claude Desktop (común con uv tool), utiliza la ruta absoluta:

"command": "/Users/you/.local/bin/sparkit-mcp"

(Encuentra la ruta con which sparkit-mcp después de uv tool install.)

Cursor

Edita ~/.cursor/mcp.json (o .cursor/mcp.json en tu proyecto):

{
  "mcpServers": {
    "sparkit": {
      "command": "sparkit-mcp",
      "env": {
        "SPARKIT_API_KEY": "sk_sparkit_..."
      }
    }
  }
}

Recarga Cursor (Cmd+Shift+P → "Reload Window").

Claude Code

claude mcp add sparkit -e SPARKIT_API_KEY=sk_sparkit_... -- sparkit-mcp

Pruébalo

Una vez configurado, pregúntale al LLM:

Usa SPARKIT para buscar la literatura más reciente sobre el papel de WRNIP1 como objetivo sintético-letal en el cáncer.

El LLM llamará a research. Espera entre 60 y 180 segundos, y luego obtendrás un informe en Markdown con citas en línea y una lista numerada de fuentes.

Configuración

Variable de entorno	Por defecto	Descripción
`SPARKIT_API_KEY`	(requerido)	Clave Bearer de https://app.sparkit.science/keys.
`SPARKIT_API_BASE`	`https://jlsteenwyk--sparkit-api-web.modal.run`	Sustituye la URL base de la API. Útil para despliegues de prueba o autohospedados.
`SPARKIT_API_TIMEOUT_SECONDS`	`30`	Tiempo de espera por solicitud HTTP. No afecta al tiempo de espera total de `research`; eso es `max_wait_seconds`.

Referencia de herramientas

`research(question, response_format?, include_citations?, max_wait_seconds?)`

Argumento	Tipo	Por defecto	Descripción
`question`	string	—	La pregunta científica. Requerido. Sé específico.
`response_format`	`"full"` o `"brief"`	`"full"`	Longitud del informe en Markdown devuelto.
`include_citations`	boolean	`true`	Mantener `true` para informes con fuentes.
`max_wait_seconds`	int (30-540)	`240`	Cuánto tiempo bloquear la espera antes de devolver el job_id con instrucciones para consultar el estado.

Devuelve Markdown. En caso de tiempo de espera agotado, devuelve una línea de estado con el job_id para que el LLM pueda llamar a get_job_status más tarde.

`get_job_status(job_id)`

Devuelve el informe en Markdown con citas si el trabajo se ha completado, una línea de estado si todavía se está ejecutando, o un mensaje de error en caso contrario.

Solución de problemas

Error de autenticación — SPARKIT_API_KEY no está configurado o no es válido. Comprueba si hay errores tipográficos en claude_desktop_config.json; reinicia Claude Desktop después de realizar cambios.

Cuota agotada — se han acabado las consultas mensuales / créditos de "Try-it". Visita https://app.sparkit.science/billing.

La herramienta no aparece en Claude Desktop — comprueba el registro de Claude Desktop:

macOS: ~/Library/Logs/Claude/mcp-server-sparkit.log
Windows: %LOCALAPPDATA%\Claude\Logs\mcp-server-sparkit.log

El problema más común es que command: sparkit-mcp no esté en el PATH; sustitúyelo por la ruta absoluta obtenida con which sparkit-mcp.

El trabajo agota el tiempo de espera — el límite de max_wait_seconds es de 540s (9 min). Para preguntas muy profundas, envía el trabajo y luego consulta get_job_status en lugar de esperar en línea. SPARKIT también cancelará automáticamente los trabajos que superen su propio límite interno.

Licencia

MIT.

mcp-sparkit