Skip to main content
Glama
Open Science MCP

Open Science MCP

by imjszhang

Open Science MCP

简体中文

Control the local Open Science research application from an MCP client. Create projects, start or continue research, inspect progress and plans, cancel runs, and read generated artifacts. Projects and sessions use Open Science's existing storage and execution engine.

This is an independent integration, inspired by blender-mcp. It is not an official AIPOCH project. The server uses local stdio MCP → authenticated loopback HTTP → Open Science. Models, research tools, approvals, and compute environments remain managed by Open Science.

Requirements

  • Node.js 22.5 or later; CI targets Node 22 and 24.

  • Open Science desktop application; the compatibility baseline is v0.29.0.

  • A running local Open Science web service, plus a configured Agent runtime and model provider for research execution.

  • An MCP client supporting local stdio servers.

See the current acceptance report, compatibility and the acceptance procedure. Automated contract tests and live application acceptance are separate checks; passing the former does not prove a configured model or a successful research run.

Related MCP server: io.github.ibondarenko1/worldfuzz

Install and start

git clone https://github.com/imjszhang/open-science-mcp.git
cd open-science-mcp
npm ci
npm run build

Install Open Science from its official releases, configure the runtime and provider in the application, and enable/start its local service. When the application CLI is installed:

open-science start --no-open
open-science doctor --json
node dist/index.js doctor

The MCP doctor command prints a credential-free report and exits with code 1 if the service is unavailable or runtime/provider readiness is false. It does not start the application or change settings. See setup for the bundled CLI invocation before an open-science launcher exists.

The documented installation is from GitHub source or a release tarball. npm publication is separate; do not assume this package is available from the npm registry.

Connect an MCP client

Add a local stdio server to your client's MCP configuration, replacing both paths with absolute paths on your computer:

{
  "mcpServers": {
    "open-science": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/open-science-mcp/dist/index.js"]
    }
  }
}

The surrounding configuration format varies by client; the server command and arguments are the same. On Windows, JSON paths can use forward slashes, such as C:/Program Files/nodejs/node.exe. Use the client's documented configuration location.

Service discovery checks ~/.open-science-project, then ~/.open-science, accepting only an authenticated healthy local service. To select one profile explicitly, append --config-root and its absolute directory to args, or set OPEN_SCIENCE_CONFIG_ROOT. See discovery and credentials.

First ask the client: “Use Open Science to check readiness and list my projects.” A running stdio server normally waits silently; stdout is reserved for MCP messages. Diagnostics go to stderr.

Tools

Tool

Purpose

Main inputs

get_status

Connection and runtime/provider readiness

None

list_projects

Project names and stable IDs

None

create_project

Create a project

name, idempotency_key; optional description, agent_context

list_sessions

Session summaries

Optional project_id

get_session

Summary and current waiting state

session_id

start_run

Start research or continue a session

project_id, prompt, idempotency_key; optional session_id, cwd, turn_intent

get_run

Status, output, attention, artifacts

run_id

wait_run

Bounded polling

run_id; optional timeout_ms (default 10,000; maximum 30,000)

cancel_run

Explicitly cancel a run

run_id

get_plan

Plan and approval state

session_id

list_artifacts

Finalized artifact metadata and resource URIs

session_id

read_artifact

Text/image preview or file download

session_id, artifact_id; optional offset, max_bytes, output_path

create_project and start_run require an idempotency_key. Generate a new key once per intended action, for example a UUID. Open Science keeps replay records in memory for 24 hours from the first request, within the same daemon lifetime. Within that window and the same instance, retry an uncertain result with the same key and identical arguments. A restart, a different instance, or expiry removes that duplicate protection: inspect the original project/session/run IDs and application UI before deciding whether to retry. Never blindly resubmit or generate a fresh key because a response was lost. A different intended action needs a different key. The server does not automatically retry mutations. Cancellation is scoped to the existing run ID and does not take a key.

Use project and session IDs, not names. get_session is a summary, not a conversation transcript. A follow-up uses the original session_id and the same canonical working directory. Omit cwd unless you need a specific existing directory. turn_intent: "plan-first" asks Open Science to plan before execution.

Research may use the model provider configured in the app. Approvals and permission requests are handled in the Open Science UI. The server preserves application permission defaults; it does not expose an approval bypass.

Waiting and results

Run statuses are running, completed, failed, and cancelled. Session waiting states are separate. wait_run returns a reason of terminal, attention, or timeout, with its latest run snapshot and a session snapshot when available. Inspect run.attention even on a terminal run. Reaching a wait deadline or closing an MCP request does not cancel accepted research; call cancel_run explicitly. If cancellation times out while draining, inspect that same run again.

Text previews use byte windows: max_bytes defaults to 65,536 and is capped at 262,144. Continue with the returned next_offset. Small PNG/JPEG/WebP/GIF images can be returned inline. Other files, or images too large for inline content, return an open-science://sessions/{sessionId}/artifacts/{artifactId} resource link.

To save a complete file up to 100 MiB, pass an absolute output_path with an existing parent directory and offset: 0. The destination must not exist; it is opened exclusively and never overwritten. A SHA-256 is returned and checked against artifact metadata when a checksum is available. See CSV example.

Development

npm ci
npm run check
npm test
npm pack

Tests use an independent local HTTP fixture and a real stdio MCP client; they require no model account. CI also installs the packed package into a clean directory and verifies tool discovery. Live validation uses the acceptance checklist.

License and credits

Apache-2.0; see LICENSE and NOTICE. Public task contracts and discovery behavior are adapted from AIPOCH Open Science. blender-mcp inspired the external-adapter-to-live-application architecture; no Blender code is included.

Available Tools

12 tools
cancel_runB
DestructiveIdempotent

Request cancellation of a specific run. Inspect the returned status, and wait again if cancellation is still draining.

Inputs: run_id (required).

create_projectA
Idempotent

Create a project visible in Open Science. Same-key retries are protected only in the same daemon lifetime within 24 hours of the first request; inspect existing projects after restart or expiry before retrying.

Inputs: name (required), idempotency_key (required), description, agent_context.

get_planC
Read-onlyIdempotent

Read the current plan and approval state. Approve or give feedback in Open Science UI.

Inputs: session_id (required).

get_runA
Read-onlyIdempotent

Get run status, current output, attention and artifacts. A terminal status can still require attention; inspect attention.

Inputs: run_id (required).

get_sessionA
Read-onlyIdempotent

Read a session summary and waiting status. This is not complete message history.

Inputs: session_id (required).

get_statusB
Read-onlyIdempotent

Inspect local service and model/runtime readiness. Does not start or configure the app.

Inputs: no named parameters.

list_artifactsB
Read-onlyIdempotent

List finalized session artifacts and MCP resource URIs.

Inputs: session_id (required).

list_projectsA
Read-onlyIdempotent

List Open Science projects and their stable IDs.

Inputs: no named parameters.

list_sessionsA
Read-onlyIdempotent

List session summaries, optionally scoped to a project ID.

Inputs: project_id.

read_artifactA
Idempotent

Read a UTF-8 text byte window, inline a small image, or return a resource link. To download a full file up to 100 MiB, supply an absolute output_path whose parent exists; existing files are never overwritten. Download checksum is verified when metadata provides it.

Inputs: session_id (required), artifact_id (required), offset, max_bytes, +1 more.

start_runA
Idempotent

Submit research (may incur model cost), or continue an existing session. cwd must match the session directory on follow-ups. Approvals stay in Open Science UI. Returns a run ID; poll/wait on that ID. Same-key retries are protected only in the same daemon lifetime within 24 hours of the first request; inspect original runs/sessions after restart or expiry.

Inputs: prompt (required), project_id (required), idempotency_key (required), cwd, +2 more.

wait_runA
Read-onlyIdempotent

Wait up to 30 seconds. Returns early on completion or user/permission/plan attention. timeout means research continues; only cancel_run cancels it.

Inputs: run_id (required), timeout_ms.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: status inspection, project management, session listing/reading, run lifecycle (start/get/wait/cancel), plan access, and artifact retrieval. No two tools overlap in function; get_run and wait_run serve different needs (status vs. waiting).

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using lowercase with underscores (e.g., list_projects, start_run, cancel_run). The naming is predictable and unambiguous.

    Tool Count5/5

    With 12 tools, the count is well within the ideal range for a domain-specific server. Each tool serves a distinct purpose in the research workflow, covering projects, sessions, runs, plans, and artifacts without redundancy.

    Completeness4/5

    The tool surface covers the core lifecycle: project creation, session listing/reading, run initiation and control, plan viewing, and artifact access. Minor gaps exist (e.g., no update/delete for projects, no explicit run listing), but these do not block primary workflows and are likely handled via other means.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP clients to drive Open Reality OS end-to-end: upload scans, follow reconstruction jobs, sync scenes as context, run measurements and path planning, execute scene agents, and export robot-training data to disk.
      41
      24 npm
      656
      BSD 2-Clause "Simplified"
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents and MCP clients to run research as an explicit scientific process: forming hypotheses, designing and executing sealed experiments, capturing observations and artifacts, linking claims to supporting evidence, and reviewing provenance. Exposes coordinated MCP services so users can inspect, reproduce, and audit every step from question to conclusion rather than trusting an opaque final answer.
      46
      21
      Apache 2.0
    • A
      license
      C
      quality
      B
      maintenance
      Enables AI clients to create and read structured research records—projects, questions, specifications, implementations, executions, artifacts, evidence, evaluations, comparisons, analyses, and reports—through MCP while keeping scientific judgments and approvals human-controlled.
      37
      1
      MIT