Open Science MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Open Science MCP Use Open Science to check readiness and list my projects."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 buildInstall 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 doctorThe 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 |
| Connection and runtime/provider readiness | None |
| Project names and stable IDs | None |
| Create a project |
|
| Session summaries | Optional |
| Summary and current waiting state |
|
| Start research or continue a session |
|
| Status, output, attention, artifacts |
|
| Bounded polling |
|
| Explicitly cancel a run |
|
| Plan and approval state |
|
| Finalized artifact metadata and resource URIs |
|
| Text/image preview or file download |
|
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 packTests 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 toolscancel_runBDestructiveIdempotent
Request cancellation of a specific run. Inspect the returned status, and wait again if cancellation is still draining.
Inputs: run_id (required).
create_projectAIdempotent
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_planCRead-onlyIdempotent
Read the current plan and approval state. Approve or give feedback in Open Science UI.
Inputs: session_id (required).
get_runARead-onlyIdempotent
Get run status, current output, attention and artifacts. A terminal status can still require attention; inspect attention.
Inputs: run_id (required).
get_sessionARead-onlyIdempotent
Read a session summary and waiting status. This is not complete message history.
Inputs: session_id (required).
get_statusBRead-onlyIdempotent
Inspect local service and model/runtime readiness. Does not start or configure the app.
Inputs: no named parameters.
list_artifactsBRead-onlyIdempotent
List finalized session artifacts and MCP resource URIs.
Inputs: session_id (required).
list_projectsARead-onlyIdempotent
List Open Science projects and their stable IDs.
Inputs: no named parameters.
list_sessionsARead-onlyIdempotent
List session summaries, optionally scoped to a project ID.
Inputs: project_id.
read_artifactAIdempotent
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_runAIdempotent
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_runARead-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
Scored across 12 tools
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).
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.
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.
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
Related MCP Connectors
Start and manage Reason cloud coding agents, projects and sessions from any MCP client.
Build, test, publish, and run Kovca workflows from AI agents over remote MCP.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Read and write shared BitsWeave context, projects, tasks, and work sessions through MCP.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables 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.4124 npm656BSD 2-Clause "Simplified"
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to run bounded robotics tasks, retrieve independently verified results, and reuse checked data or artifacts from the local WorldFuzz platform.MIT
- AlicenseAqualityBmaintenanceEnables 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.4621Apache 2.0
- AlicenseCqualityBmaintenanceEnables 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.371MIT