sparkit-mcp

SPARKIT용 MCP 서버 — Claude Desktop, Cursor, Claude Code 또는 기타 MCP 호환 클라이언트에서 과학 연구 에이전트를 호출하세요.

두 가지 도구가 제공됩니다:

• research — 과학적 질문을 제출합니다. SPARKIT이 문헌을 검색하고 관련 논문을 읽은 뒤, 인용이 포함된 마크다운 보고서를 반환합니다. 작업이 완료될 때까지 대기(기본값 4분)한 후 전체 보고서를 인라인으로 반환합니다.

• get_job_status — 이전에 제출된 작업을 ID로 가져옵니다. research가 작업 완료 전에 반환되었거나 이전 보고서를 다시 확인할 때 유용합니다.

설치

uv tool install sparkit-mcp

또는 pip 사용:

pip install sparkit-mcp

둘 다 sparkit-mcp 콘솔 스크립트를 설치합니다. (사전 릴리스: 첫 번째 PyPI 릴리스가 나올 때까지 uv tool install "git+https://github.com/SPARKIT-science/sparkit-mcp.git"을 사용하여 GitHub에서 직접 설치하세요.)

API 키 받기

1. https://app.sparkit.science/signup 에서 가입하세요 (Try-it은 5회 쿼리에 $10이며, 구독은 월 $50부터 시작합니다).

2. https://app.sparkit.science/keys 를 방문하여 키를 생성하세요.

3. 키를 복사하세요 — 한 번만 표시됩니다.

MCP 클라이언트 구성

Claude Desktop

claude_desktop_config.json을 편집하세요:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

추가:

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

Claude Desktop을 다시 시작하세요. 채팅 입력창 옆의 도구 아이콘에 sparkit이 나타나야 합니다.

sparkit-mcp가 Claude Desktop의 PATH에 없는 경우(uv tool 사용 시 흔함), 절대 경로를 사용하세요:

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

(uv tool install 후 which sparkit-mcp로 경로를 찾으세요.)

Cursor

~/.cursor/mcp.json (또는 프로젝트 내 .cursor/mcp.json)을 편집하세요:

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

Cursor를 새로고침하세요 (Cmd+Shift+P → "Reload Window").

Claude Code

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

사용해 보기

구성이 완료되면 LLM에게 다음과 같이 질문하세요:

SPARKIT을 사용하여 암에서 합성 치사 표적으로서의 WRNIP1 역할에 대한 최신 문헌을 찾아보세요.

LLM이 research를 호출합니다. 60~180초 정도 기다리면 인라인 인용과 번호가 매겨진 출처 목록이 포함된 마크다운 보고서가 제공됩니다.

구성

도구 참조

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

마크다운을 반환합니다. 타임아웃 시, LLM이 나중에 get_job_status를 호출할 수 있도록 job_id가 포함된 상태 줄을 반환합니다.

get_job_status(job_id)

작업이 완료되었으면 인용된 마크다운 보고서를 반환하고, 여전히 실행 중이면 상태 줄을, 그렇지 않으면 오류 메시지를 반환합니다.

문제 해결

인증 실패 — SPARKIT_API_KEY가 설정되지 않았거나 유효하지 않습니다. claude_desktop_config.json에 오타가 있는지 확인하고, 편집 후 Claude Desktop을 다시 시작하세요.

할당량 초과 — 월간 쿼리/Try-it 크레딧이 소진되었습니다. https://app.sparkit.science/billing 을 방문하세요.

Claude Desktop에 도구가 나타나지 않음 — Claude Desktop 로그를 확인하세요:

• macOS: ~/Library/Logs/Claude/mcp-server-sparkit.log

• Windows: %LOCALAPPDATA%\Claude\Logs\mcp-server-sparkit.log

가장 흔한 문제는 command: sparkit-mcp가 PATH에 없는 경우입니다. which sparkit-mcp로 확인한 절대 경로로 대체하세요.

작업 타임아웃 — max_wait_seconds의 최대값은 540초(9분)입니다. 매우 심도 있는 질문의 경우, 인라인으로 기다리지 말고 제출 후 get_job_status를 폴링하세요. SPARKIT은 자체 내부 제한을 초과하는 작업도 자동으로 취소합니다.

라이선스

MIT.