How do I use marimo-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@marimo-mcp list my running marimo notebooks" 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.

marimo-mcp

by Vladisluv12

Overview Schema Source Related Servers Discussions Admin

Python

Local

marimo-mcp

A single MCP server that auto-discovers all running marimo notebooks and exposes tools for reading, editing, and running cells — no --mcp flag required.

Works with two backends:

HTTP mode — connects to marimo notebooks running via marimo edit (standard server)
VS Code mode — connects to marimo notebooks open in VS Code via the companion bridge extension

Architecture

Claude / MCP client
       │
       ▼
  marimo-mcp (Python MCP server)
       │
       ├─── HTTP backend ──────► marimo edit --no-token notebook.py
       │                         (port 2718 by default)
       │
       └─── VS Code backend ───► marimo-mcp-bridge (VS Code extension)
                                  │  port 42018
                                  ▼
                            vscode.commands.executeCommand('marimo.api', ...)
                                  │
                                  ▼
                          marimo VS Code extension

Discovery runs on every tool call (cached 5 s):

Scans running processes for marimo commands, extracts ports
For each port: fetches the HTML page to extract Marimo-Server-Token, then queries /api/home/running_notebooks
Checks if the bridge extension is running on port 42018 and appends any VS Code notebooks

VS Code backend — how cell execution works:

marimo's VS Code extension does not expose an HTTP server. The bridge extension (marimo-mcp-bridge) fills this gap — it runs a small HTTP server inside VS Code and forwards calls through VS Code's notebook execution pipeline (notebook.cell.execute → executeHandler → marimo LSP → kernel). This means edit_and_run_cell updates the cell visually in VS Code and returns actual stdout/stderr output.

VS Code backend — get_deps and get_variables:

These tools use static analysis of the .py file via marimo's own AST engine. No kernel or bridge needed — just the file on disk. get_variables returns variable names and their kinds (variable, import, function, class); values are only available via the HTTP backend with a running session.

Related MCP server: jupyter-interactive-mcp

Installation

1. Python MCP server

Requires Python 3.11+ and uv.

git clone <repo>
cd marimo-mcp
uv sync          # creates .venv and installs all dependencies

2. VS Code bridge extension (for VS Code notebooks)

cd marimo-mcp-bridge
npm install
bash install.sh  # compiles TypeScript, packages as VSIX, installs in VS Code

After installing, reload VS Code window (Developer: Reload Window).

For subsequent updates after code changes, just run bash install.sh again.

Configuration

MCP settings

Add to .vscode/mcp.json or Claude Code's MCP config:

{
  "mcpServers": {
    "marimo": {
      "command": "uv",
      "args": ["run", "marimo-mcp"],
      "cwd": "/path/to/marimo-mcp",
      "env": {
        "MARIMO_TOKEN": "optional — only needed if marimo started with token auth"
      }
    }
  }
}

uv run automatically uses the .venv created by uv sync.

Token authentication

By default marimo generates a random access token. Either:

Start marimo with --no-token to disable authentication, or
Set MARIMO_TOKEN to the token from the startup URL (?access_token=...)

Tools

Tool	HTTP	VS Code	Description
`list_notebooks`	✓	✓	List all discovered notebooks
`create_notebook`	✓	✓	Create a new `.py` notebook file
`get_cells`	✓	✓	List cells with IDs and code
`get_cell_outputs`	✓	—	Visual output and console streams
`get_errors`	✓	—	All errors grouped by cell
`get_variables`	✓ (with values)	✓ (names/kinds only)	Variables in the notebook
`get_deps`	✓	✓	Cell dependency graph
`add_cell`	✓	✓	Add a new cell (not executed); `cell_type="markdown"` for markup
`edit_and_run_cell`	✓	✓	Edit a cell and run it, returns stdout/stderr
`delete_cell`	✓	✓	Delete a cell

get_cell_outputs and get_errors return an explicit error for VS Code notebooks. Use edit_and_run_cell with print() calls to inspect values.

`add_cell` parameters

add_cell(notebook, code, after_cell_id=None, cell_type="code")

cell_type="code" — standard Python cell (default)
cell_type="markdown" — markdown cell; in VS Code uses native NotebookCellKind.Markup (renders immediately without execution); in HTTP mode wraps in mo.md(...)

Current limitations

VS Code output is stdout/stderr only — rich outputs (plots, dataframes, marimo UI elements) are not captured via the bridge. Use the HTTP backend (marimo edit --no-token) for full output access.

Claude Code skill

A Claude Code skill for working with this MCP server is available at ~/.claude/plugins/marketplaces/marimo-mcp/SKILL.md. It's enabled automatically when the marimo-mcp@marimo-mcp plugin is active in your Claude Code settings.

This skill is complementary to marimo-pair (which handles marimo edit HTTP mode). Use marimo-mcp when the notebook is open in VS Code.

Testing guide

Test 1: HTTP backend (marimo running locally)

Start a notebook:

marimo edit --no-token --port 2718 /tmp/test_notebook.py

Verify discovery:

uv run python -c "
import asyncio
from marimo_mcp.discovery import discover_notebooks
async def main():
    nbs = await discover_notebooks()
    for nb in nbs:
        print(f'{nb.name}  port={nb.port}  via={\"vscode\" if nb.is_lsp else \"http\"}')
asyncio.run(main())
"

Edit and run a cell:

import asyncio
from marimo_mcp.server import get_cells, edit_and_run_cell

async def main():
    cells = await get_cells('test_notebook.py')
    # get a cell_id from the output
    result = await edit_and_run_cell('test_notebook.py', 'CELL_ID', 'x = 6 * 7\nprint(x)')
    print(result)  # {"output": "42", "stdout": "42\n", ...}

asyncio.run(main())

Test 2: VS Code bridge extension

Verify bridge is running:

curl -s http://127.0.0.1:42018/health
# {"status":"ok"}

List open VS Code notebooks:

curl -s http://127.0.0.1:42018/notebooks | python3 -m json.tool

Full round-trip (edit + run + get output):

import asyncio
from marimo_mcp.server import get_cells, edit_and_run_cell

async def main():
    cells = await get_cells('goyda.py')  # VS Code notebook
    cell_id = ...  # from cells output
    result = await edit_and_run_cell('goyda.py', cell_id, 'print(6 * 7)')
    print(result)  # {"output": "42", "stdout": "42\n", "stderr": ""}

asyncio.run(main())

Test 3: Unit tests

uv run pytest tests/ -v

25 tests should pass, covering MarimoClient, discovery logic, and notebook creation.

Troubleshooting

No notebooks found, but marimo is running:

Run with --no-token, or set MARIMO_TOKEN
Confirm the port is accessible: curl http://localhost:2718/

Bridge not available (connection refused on port 42018):

Check the VS Code Output panel for "marimo-mcp-bridge" channel
Make sure a .py marimo notebook is open — the marimo.api command is only available when the marimo extension is active

Bridge needs reinstalling after code changes:

cd marimo-mcp-bridge
bash install.sh
# Then: Developer: Reload Window in VS Code

edit_and_run_cell returns empty output or times out (VS Code):

The cell execution uses VS Code's notebook pipeline. If it times out (15s default):

Check VS Code Output → marimo for kernel startup errors
Make sure the notebook is open and visible (not just in the background)
Try running a cell manually first to warm up the kernel

Wrong Python executable (kernel fails to start):

The bridge resolves Python in this order:

.venv/bin/python next to the notebook file
.venv/bin/python in any VS Code workspace folder
VS Code Python extension active environment
python3 (system fallback)

Create a .venv with marimo in the workspace root:

python3 -m venv .venv
.venv/bin/pip install marimo

Available Tools

10 tools

add_cellA

Add a new cell to a notebook without executing it.

Args: notebook: Path to the notebook file or port number. code: Content for the new cell. after_cell_id: Insert after this cell ID. If None, appends at end. cell_type: "code" (default) or "markdown". Markdown wraps content in mo.md(...).

ParametersJSON Schema

Name	Required	Default
`notebook`	Yes
`code`	Yes
`after_cell_id`	No
`cell_type`	No	code

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses non-execution, the behavior of cell_type (Markdown wrapped in mo.md(...)), and the semantics of after_cell_id (append if None). Missing details like error handling or prerequisites, but adequate for a straightforward tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: a one-sentence purpose followed by a bullet-like Args section. Every sentence adds value, and the structure front-loads the key action. No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema (not shown but indicated), the description does not need to explain return values. It covers purpose, param semantics, and key behavioral traits. Could mention constraints or error cases, but overall sufficient for the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, so the description compensates fully. Each parameter is explained: notebook (path or port), code (content), after_cell_id (insert position), cell_type (with default and Markdown detail). This adds significant meaning beyond the schema titles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Add a new cell to a notebook without executing it', which is a specific verb-resource combination. It differentiates from sibling tools like edit_and_run_cell (which involves execution) and delete_cell (which removes cells).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly notes that the tool adds without executing, providing clear context for when to use this tool versus alternatives like edit_and_run_cell. However, it does not explicitly list when not to use it or other sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_notebookA

Create a new marimo notebook at the given absolute path.

Args: path: Absolute path where the .py notebook file will be created.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must disclose behavioral traits. It only states 'create' without mentioning whether overwriting an existing file is allowed, required permissions, or side effects. This is insufficient for a creation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with only two sentences covering the purpose and parameter. Every part is necessary and there is no wasted text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool is a simple creation with one parameter, the description covers the basic action. However, it lacks details about output (though output schema exists) and behavior on conflicts. It is minimally adequate but could be more complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'path' is described as 'Absolute path where the .py notebook file will be created.' This adds meaningful context beyond the schema, which has no description. The explanation is clear and specific.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Create a new marimo notebook at the given absolute path' with a specific verb and resource. It distinguishes from sibling tools like add_cell or delete_cell which operate on cells, not notebooks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, such as when to use list_notebooks or edit_and_run_cell. The description lacks context for appropriate usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_cellA

Delete a cell from a running notebook.

Args: notebook: Path to the notebook file or port number. cell_id: The cell ID to delete (get IDs from get_cells first).

ParametersJSON Schema

Name	Required	Description	Default
`notebook`	Yes
`cell_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description should cover behavioral traits. It only states the basic action without disclosing destructiveness, irreversibility, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with one sentence and a brief args note, front-loading the purpose with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a simple delete tool with two parameters and an output schema, though it could mention whether changes are auto-saved or any restrictions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds value beyond schema by clarifying notebook as 'path or port number' and advising to obtain cell_id from get_cells, compensating for 0% schema description coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Delete a cell from a running notebook', specifying a specific verb and resource, and distinguishes from siblings like add_cell.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides guidance to get IDs from get_cells first, but does not mention when not to use this tool or compare with alternatives like edit_and_run_cell.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

edit_and_run_cellA

Edit a cell's code and run it. Waits for completion and returns outputs.

This does NOT require --mcp flag or agent mode.

Args: notebook: Path to the notebook file or port number. cell_id: The cell ID to edit (get IDs from get_cells first). code: New Python code for the cell.

ParametersJSON Schema

Name	Required	Description	Default
`notebook`	Yes
`cell_id`	Yes
`code`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description explains that the tool waits for completion and returns outputs. It does not disclose potential side effects of running code or error handling, which would enhance transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is brief and front-loaded with the main action. Every sentence serves a purpose, with no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The output schema covers return values. The description covers core functionality and prerequisites, but could address error cases and side effects more thoroughly for a tool that executes code.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All three parameters are described succinctly in the description, adding meaningful context beyond the empty input schema. The descriptions note the type and purpose of each parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool edits a cell's code and runs it, specifying the verb and resource. It distinguishes from siblings like add_cell, delete_cell, and get_cells.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions that the --mcp flag or agent mode is not required and advises to get cell IDs from get_cells first, providing context. However, it does not explicitly state when not to use this tool or list alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_cell_outputsA

Get visual output and console streams for cells.

Args: notebook: Path to the notebook file or port number. cell_ids: List of cell IDs to get outputs for. If empty, returns all cells.

ParametersJSON Schema

Name	Required	Description	Default
`notebook`	Yes
`cell_ids`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavior. It states output retrieval but doesn't clarify what happens for cells with no output, error cells, or whether the tool modifies state. No mention of read-only nature despite being a retrieval operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise, with a clear one-line purpose followed by parameter explanations. No redundant sentences; every part adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists, return value details are covered elsewhere. However, the description lacks context about when outputs are available (e.g., after cell execution) and does not address edge cases like missing cell IDs. Adequate but not comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description compensates by explaining the notebook parameter can be a path or port, and cell_ids defaults to returning all cells when empty. This adds meaning beyond the schema's type definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves visual output and console streams for cells, using a specific verb 'Get' and specifying the resource (cells). It distinguishes from siblings like get_cells (which lists cells) and get_errors (which only gets errors).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives (e.g., get_errors for errors only, get_cells for cell metadata). It doesn't mention prerequisites like cells must execute first or that it's for post-execution inspection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_cellsA

Get all cells with their IDs, code, and runtime state.

Args: notebook: Path to the notebook file or port number (e.g. "analysis.py" or "2718").

ParametersJSON Schema

Name	Required	Description	Default
`notebook`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full responsibility. It discloses the tool returns cell IDs, code, and runtime state, implying a read operation. However, it does not explicitly state side effects, safety, or permission requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two sentences and an Args block. Every sentence adds value, and the main purpose is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has one required parameter and an output schema (as per context). The description explains the return content sufficiently given the output schema handles the rest. It is complete for a simple getter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description adds crucial meaning by defining 'notebook' as a path or port number with examples. This compensates for the lack of schema-level documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and resource 'cells', and specifies what is returned (IDs, code, runtime state). It distinguishes from sibling tools like get_cell_outputs or get_errors by focusing on the cells themselves.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes an Args section explaining the notebook parameter but does not provide explicit guidance on when to use this tool vs alternatives like get_cell_outputs. Usage is implied but not elaborated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_depsA

Get the cell dependency graph showing which cells depend on which variables.

Args: notebook: Path to the notebook file or port number. cell_id: Optional cell ID to get deps for a specific cell only.

ParametersJSON Schema

Name	Required	Description	Default
`notebook`	Yes
`cell_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It describes the output as a graph but does not mention side effects, performance, or whether it is read-only. The description is minimal beyond the basic function.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with a one-line summary and a clear parameter list. It avoids unnecessary information and is well-structured for quick comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the tool has an output schema, the description provides the basic purpose and parameter details. However, it lacks explanation of the returned graph's structure, potential errors, or performance considerations, making it somewhat incomplete for a complex tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explains the 'notebook' parameter as 'Path to the notebook file or port number' and 'cell_id' as 'Optional cell ID to get deps for a specific cell only', adding significant meaning beyond the schema's type-only specifications. With 0% schema description coverage, this provides necessary context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'get the cell dependency graph' with a specific verb and resource, distinguishing it from sibling tools like get_cells or get_variables. It specifies the output as 'showing which cells depend on which variables', leaving no ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for retrieving dependency information but does not explicitly guide when to use this tool over alternatives. No mention of prerequisites or context when the tool is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_errorsB

Get all errors in the notebook, grouped by cell.

Args: notebook: Path to the notebook file or port number.

ParametersJSON Schema

Name	Required	Description	Default
`notebook`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose behavioral traits such as side effects, performance impact, or what happens when no errors exist. It lacks transparency for a tool that likely involves I/O.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with no unnecessary words, fitting within two sentences. However, the structure could be improved by separating the parameter description more clearly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema, the description does not need to detail return values. However, it lacks context about behavior when there are no errors, error handling, or prerequisites, making it incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description adds minimal meaning by clarifying the 'notebook' parameter as a path or port number. However, it lacks examples, format constraints, or further elaboration.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves errors grouped by cell, with a specific verb and resource. It distinctly separates itself from siblings like get_cells or get_cell_outputs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, no prerequisites, and no exclusion criteria. The description simply states what it does without usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_variablesB

Get all variable values and data tables in the notebook.

Args: notebook: Path to the notebook file or port number.

ParametersJSON Schema

Name	Required	Description	Default
`notebook`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must disclose behavioral traits. It implies read-only access but does not state side effects, authorization needs, or error handling. Output schema exists but behavior beyond basic description is not explained.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: one for purpose, one listing parameter. No wasted words, but could be slightly more structured (e.g., separate sections). Length is appropriate for a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one parameter and an output schema, the description covers the basic purpose and parameter meaning. However, it does not describe the return structure or any limitations, leaving gaps despite the schema existing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Description adds 'Path to the notebook file or port number' for the 'notebook' parameter, which goes beyond the schema's type string. However, there is no further detail on format or constraints, and schema description coverage is 0%, so partial compensation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Get all variable values and data tables in the notebook.' The verb 'Get' and resource 'variable values and data tables' are specific, and the tool is distinct from siblings like get_cells or get_errors.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., get_cell_outputs). The description only explains functionality without context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_notebooksA

List all running marimo notebooks with their paths and ports.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose any behavioral traits beyond the basic purpose. It omits details like authentication, blocking behavior, or what happens if no notebooks are running.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence front-loading the action and result, with no unnecessary words. Highly concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description mentions paths and ports, aligning with the output schema. It lacks mention of possible empty results or pagination, but given the simplicity, it is mostly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, and schema coverage is 100%. The description does not need to add parameter information, so it meets the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'list', the resource 'running marimo notebooks', and the returned data 'paths and ports'. It distinguishes from sibling tools like create_notebook or get_cells.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for listing running notebooks, but does not explicitly state when to use it or provide alternatives. The context of sibling tools helps, but the description itself lacks such guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

10 tool updatesv0.1.0May 27, 2026
- First observedadd_cell
- First observedcreate_notebook
- First observeddelete_cell
- First observededit_and_run_cell
- First observedget_cell_outputs
- First observedget_cells
- First observedget_deps
- First observedget_errors
- First observedget_variables
- First observedlist_notebooks

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored 2026-05-27 04:00 across 10 tools

Disambiguation5/5

Each tool targets a distinct operation: notebook creation, cell manipulation (add, delete, edit/run), and retrieval of cells, outputs, deps, errors, variables, and running notebooks. No functional overlap.

Naming Consistency5/5

All tool names follow a clear verb_noun pattern in snake_case (e.g., `create_notebook`, `get_cells`). Minor length variation does not break consistency.

Tool Count5/5

10 tools cover the essential CRUD and inspection workflows for marimo notebooks. The count is well-scoped for a focused MCP server.

Completeness4/5

The set covers core notebook lifecycle (create, list, add/delete/edit/run cells) and introspection (cells, outputs, errors, dependencies, variables). Missing operations like save, rename, or reorder cells, but not critical for typical agent tasks.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Workflow A
io.github.Jonnyton
Create, browse, remix, collaborate on, and run durable AI workflow nodes from MCP hosts.
Autonomous Agents App Automation Workplace & Productivity
21
Agentic Mermaid A
io.github.adewale
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Data Visualization Software Architecture
9210
Atako A
ai.atako
Remote MCP server to read and manage your Atako AI agents, messages, files, and integrations.
Agent Orchestration AI & Machine Learning
31
ctlsurf
com.ctlsurf
System-of-record notebook for AI coding agents: pages, datastores, tasks, skills over MCP.
Knowledge & Memory Developer Tools Autonomous Agents
2

Related MCP Servers

vscode-notebook-mcp
Developer Tools Code Execution
caryan
A
license
Not graded
quality
D
maintenance
Exposes VSCode Jupyter notebooks to MCP-compatible AI agents, enabling them to read, edit, and run cells against the same kernel.
Updated 3 months ago (2026-05-31 19:57 UTC)
MIT
jupyter-interactive-mcp
tsundokum
A
license
Not graded
quality
D
maintenance
An MCP server that gives any MCP-compatible LLM client full control over a live JupyterLab instance.
Updated 6 months ago (2026-03-01 21:05 UTC)
MIT
Agentic Jupyter MCP
Developer Tools Code Execution
koyo922
A
license
Not graded
quality
A
maintenance
VS Code extension that bridges local Jupyter Notebooks with AI Agents via MCP, enabling direct control of the active notebook tab.
Updated 17 days ago (2026-08-27 05:56 UTC)
2
MIT
VS Code Jupyter MCP Server
Developer Tools Code Execution
Happypig375
A
license
Not graded
quality
B
maintenance
Enables external agents to run, edit, create, and manage the Jupyter notebook the user is actively editing in VS Code, headlessly and without approval dialogs. Works with any MCP client and is Jupyter-optional for document operations.
Updated 7 days ago (2026-09-06 23:17 UTC)
1
MIT

marimo-mcp

Architecture

Installation

1. Python MCP server

2. VS Code bridge extension (for VS Code notebooks)

Configuration

MCP settings

Token authentication

Tools

add_cell parameters

Current limitations

Claude Code skill

Testing guide

Test 1: HTTP backend (marimo running locally)

Test 2: VS Code bridge extension

Test 3: Unit tests

Troubleshooting

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

`add_cell` parameters