marimo-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., "@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
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 extensionDiscovery runs on every tool call (cached 5 s):
Scans running processes for
marimocommands, extracts portsFor each port: fetches the HTML page to extract
Marimo-Server-Token, then queries/api/home/running_notebooksChecks 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 dependencies2. 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 CodeAfter 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-tokento disable authentication, orSet
MARIMO_TOKENto the token from the startup URL (?access_token=...)
Tools
Tool | HTTP | VS Code | Description |
| ✓ | ✓ | List all discovered notebooks |
| ✓ | ✓ | Create a new |
| ✓ | ✓ | List cells with IDs and code |
| ✓ | — | Visual output and console streams |
| ✓ | — | All errors grouped by cell |
| ✓ (with values) | ✓ (names/kinds only) | Variables in the notebook |
| ✓ | ✓ | Cell dependency graph |
| ✓ | ✓ | Add a new cell (not executed); |
| ✓ | ✓ | Edit a cell and run it, returns stdout/stderr |
| ✓ | ✓ | 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 nativeNotebookCellKind.Markup(renders immediately without execution); in HTTP mode wraps inmo.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.pyVerify 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.toolFull 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/ -v25 tests should pass, covering MarimoClient, discovery logic, and notebook creation.
Troubleshooting
No notebooks found, but marimo is running:
Run with
--no-token, or setMARIMO_TOKENConfirm 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
.pymarimo notebook is open — themarimo.apicommand 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 Codeedit_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/pythonnext to the notebook file.venv/bin/pythonin any VS Code workspace folderVS 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 marimoAvailable Tools
10 toolsadd_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(...).
Inputs: notebook (required), code (required), after_cell_id, cell_type. Returns: result
create_notebookA
Create a new marimo notebook at the given absolute path.
Args: path: Absolute path where the .py notebook file will be created.
Inputs: path (required). Returns: result
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).
Inputs: notebook (required), cell_id (required). Returns: result
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.
Inputs: notebook (required), cell_id (required), code (required). Returns: result
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.
Inputs: notebook (required), cell_ids. Returns: result
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").
Inputs: notebook (required). Returns: result
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.
Inputs: notebook (required), cell_id. Returns: result
get_errorsB
Get all errors in the notebook, grouped by cell.
Args: notebook: Path to the notebook file or port number.
Inputs: notebook (required). Returns: result
get_variablesB
Get all variable values and data tables in the notebook.
Args: notebook: Path to the notebook file or port number.
Inputs: notebook (required). Returns: result
list_notebooksA
List all running marimo notebooks with their paths and ports.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
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.
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.
10 tools cover the essential CRUD and inspection workflows for marimo notebooks. The count is well-scoped for a focused MCP server.
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
Related MCP Connectors
Create, browse, remix, collaborate on, and run durable AI workflow nodes from MCP hosts.
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Unofficial Hyperbrowser MCP — wraps the Hyperbrowser AI-agent browsing API (hyperbrowser.ai).…
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceExposes VSCode Jupyter notebooks to MCP-compatible AI agents, enabling them to read, edit, and run cells against the same kernel.MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives any MCP-compatible LLM client full control over a live JupyterLab instance.MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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.1MIT
- AlicenseNot gradedqualityBmaintenanceExposes Jupyter notebook operations as MCP tools over plain HTTP, allowing AI agents to explore, edit, run, and debug notebooks in a live VS Code session using local or remote kernels.3MIT