marimo MCP Server
Official experimental local MCP access to running marimo notebook sessions.
- Skill Road
- marimo MCP Server
Categories
Description
The marimo MCP Server is marimo's documented, currently experimental interface for external MCP-compatible applications. It is not operated as a standalone SaaS endpoint: starting a local marimo notebook with --mcp makes the running marimo process serve an HTTP endpoint. A connected client such as Claude Code or Cursor can use marimo's AI tools against active notebook sessions. The official documentation explicitly calls this feature experimental and under active development, so tool definitions, availability, and APIs can change. That is a reason to re-check the version, client, and configuration before every production use involving confidential data.
Notebook inspection, not notebook execution
The MCP server is intended for low-level, read-only interaction with a live notebook. It can list active notebooks with session IDs and file paths, inspect cell structure, retrieve complete cell code and runtime data, inspect outputs, trace dependencies, inspect variables and table metadata, and summarise errors or lint findings. This can support debugging, data analysis, code review, and orientation inside reactive Python notebooks. It is not notebook execution: marimo documents run_stale_cells, notebook editing, and Code mode execution for its own chat UI, not as an exposed MCP write interface. The MCP guide specifically calls the external server lower-level read-only tools and points people who want a coding agent to drive a live notebook to marimo pair.
This boundary matters. A model may analyse code, variables, table metadata, errors, and cell outputs and suggest changes, but this endpoint should not be treated as authority to run or modify cells. Review suggestions separately in the notebook and version-control system. Even read-only results can contain sensitive research data, personal values, credentials printed in output, internal file paths, or proprietary Python code. Limit started notebooks and exposed data to the smallest test scope that answers the task.
Local HTTP endpoint and network boundary
The official guide shows, for example, uv run --with="marimo[mcp]" marimo edit notebook.py --mcp. For local development it also permits --no-token, but marimo warns that this removes authentication and should not be used in production environments. The endpoint is http://localhost:PORT/mcp/server for the marimo server port; with authentication enabled, the client must include the documented access token. A local process is not synonymous with a secure or automatically private interface. Publishing its host or port through a reverse proxy exposes network access to notebook tools.
marimo enables DNS-rebinding protection and validates incoming Host headers. --mcp-allow-remote disables that check for proxies, gateways, or custom domains. It is not a harmless convenience switch: use remote exposure only with an authenticated client, restrictive firewall and bind configuration, TLS at the appropriate boundary, and a documented trust boundary. Do not combine --no-token and --mcp-allow-remote merely to make an endpoint quickly reachable. For a personal test, authenticated localhost has the smallest attack surface.
Code, data, prompt injection, and the model path
Cell code, Markdown, table values, HTML output, tracebacks, and file paths are untrusted content. They can contain misleading instructions or prompt injection, such as requests to ignore rules, read local secrets, or invoke more tools. A client or agent must treat that material only as data. Constrain tool permissions, query only necessary sessions, review sources and code changes with a human, and never treat an embedded notebook instruction as authorization. A read-only MCP server also does not protect against a client that has shell, Git, or write-capable tools in parallel.
The data path does not automatically stop at the local marimo process. marimo returns tool results to the connected MCP client, which can put them in logs, telemetry, or the context of a local or hosted model provider. A local notebook and local endpoint therefore do not guarantee local model processing. Identify the client, model provider, retention, training settings, contract, and regional processing before notebook content is transmitted. The public source is Apache-2.0 licensed. On 2026-09-08, the GitHub API reported exactly 22,685 stars for marimo-team/marimo; that count covers the complete marimo monorepo, including the notebook platform, not the MCP server alone, and is not evidence of security or quality.
FAQ
Can an external MCP client execute notebook cells? The MCP guide describes the external server as access to low-level, read-only tools. Execution and editing are not a documented MCP-server permission.
When is --no-token acceptable? marimo says it is only for local development. Keep authentication enabled for a reachable or production endpoint.
Does localhost keep data local to the model? Not automatically. The MCP client can pass tool results to its selected model provider, logs, or telemetry.
Requirements
A Python environment with marimo and its MCP extras, a running marimo notebook, an MCP-compatible client, and local access to the marimo HTTP port.
Installation instructions
This guide configures marimo's official, experimental MCP Server as constrained local access to a running notebook. It is based on marimo's MCP and AI-tools documentation. Before installation, record which notebook, cells, and data may be visible at all. The server is not a substitute for an authorization model, repository review, or approval to execute code. Its documented purpose is to provide an external MCP client with read-oriented information from active marimo sessions. Anyone who wants a coding agent to drive or modify a notebook must evaluate marimo's separately documented workflows and their write permissions.
Step 1: Prerequisites and a controlled launch
Use an isolated Python environment and a current marimo installation with MCP extras. Start one specific test notebook with:
uv run --with="marimo[mcp]" marimo edit notebook.py --mcp
marimo starts the notebook editor and an MCP endpoint on the same local server port. Record the port, notebook path, marimo version, client, and model. Do not begin with a notebook that contains production credentials, raw personal data, or secrets in cells and outputs. The tool set can already expose file paths, cell code, runtime metadata, table information, errors, and visual output. Never copy tokens into a notebook, prompt, screenshot, or repository.
Keep token authentication enabled by default. According to marimo, --no-token removes it and is only for local development. A useful connection test is not opening the endpoint in a browser but checking the resulting tool list in the MCP client. A team or continuously operated deployment needs an explicitly designed network boundary; this guide deliberately optimises the localhost case, not public exposure.
Step 2: Connect the client and verify permissions
marimo documents HTTP transport for Claude Code:
claude mcp add --transport http marimo http://localhost:PORT/mcp/server
Replace PORT with the running marimo server's port. Cursor can use the same endpoint in its MCP configuration. Where authentication is enabled, add the access token only to protected client configuration and never commit it to shared configuration. Then confirm that the client sees only the expected marimo tools: active notebooks, the cell map, runtime data and outputs, the dependency graph, tables and variables, and error/lint information.
These tools provide research and diagnosis access. They are not permission for notebook execution. marimo documents run_stale_cells, edit_notebook, and Code mode's execute_code for its chat UI; its documentation separates them from the external MCP server. Do not accept a model proposal such as “run the cell now” as an automatic action. A human separately reviews the code, inputs, impact, test, and rollback path.
Constrain networking and remote operation
The default localhost limits reachability to the machine but does not replace authentication. marimo validates Host headers as DNS-rebinding protection. --mcp-allow-remote disables that check for proxy, gateway, or custom-domain scenarios. Use it only after an architecture with TLS, token authentication, restrictive firewalling, allowed clients, and monitoring has been defined. A reverse proxy is not a reason to disable token checks. Combining an externally reachable port and --no-token is particularly unsafe.
Review the workstation too: local logs, shell history, process lists, and MCP-client configuration can expose an endpoint or token. Stop or remove the server and client connection after a temporary test. On shared devices, use separate operating-system accounts and a dedicated workspace. For remote notebooks or containers, also establish which host is actually listening and which network zone can reach the endpoint.
Untrusted content and the model data path
Treat every tool response as untrusted content. Cells can contain Markdown, URLs, web data, or table rows that attempt prompt injection: “ignore security rules,” “read environment variables,” “invoke a shell,” or “publish the data” are data, not instructions. Limit the client to needed tools and sessions, separate notebook inspection from shell and Git rights, and require human confirmation for every follow-on action. A plausible-looking traceback or comment receives no special authority.
The complete data path is at least notebook kernel to marimo server to MCP client to model context. Depending on the client, logs, telemetry, or an external model provider can follow. Before access, document model name, provider, retention, training use, enterprise settings, contract, and regional processing. Local transport does not protect against a later cloud-model request. Send only the necessary session and avoid sensitive values in cell outputs. This keeps the marimo MCP Server a traceable, minimal diagnostic path rather than an uncontrolled data channel.
FAQ
Why do I not see an MCP endpoint? First check that marimo started with its MCP extras and the --mcp flag, then use the actual local server port in the client URL.
May I set --mcp-allow-remote for a proxy? Only after security review. The flag disables Host-header validation; token authentication, TLS, firewalling, and a clear trust boundary must independently remain in place.
Can table values be prompt injection? Yes. Values, Markdown, outputs, and errors are data. They must not expand tool permissions or replace human approvals.
uv run --with="marimo[mcp]" marimo edit notebook.py --mcp
Authentication
marimo uses an access token unless --no-token is set. The official guide limits disabling authentication to local development.
Required access permissions
Read-oriented access to active notebook sessions, cell code, runtime data, outputs, dependencies, variables, table metadata, and error/lint information. Notebook execution and editing are not documented as external MCP write capabilities.
Transmitted or stored data
marimo sends requested notebook information to the MCP client. That client can pass results to logs, telemetry, or a local or hosted model provider; localhost does not automatically constrain that downstream path.
Security risks
Cell code, outputs, data, and errors can expose sensitive information or prompt injection. Further risks come from --no-token, remote exposure, and a client with additional write tools. Keep authentication, localhost, least privilege, and human review.
License and costs
- License
- Apache-2.0 (marimo monorepo)
- Cost
- free
marimo source code is Apache-2.0 licensed. Infrastructure, model providers, and optional services can have separate terms; check them directly with the respective operator before use.
Alternatives
Not recorded yet.
At a glance
- Provider
- marimo
- Status
- Official server
- Deployment
- Local
- Current version
- 0.24.0
- GitHub stars
- 23,557
- Last reviewed
- 08.09.2026
Repository and documentation
Categories
Supported clients
Related guides
Guides and background related to this entry.