A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
improvement(docs): add documentation for mcp server, client, tools, and chat panel modes (#6744)
Joaquin Corominad4d8c656c4c8
diff --git a/docs/_static/docs-mcp-client-settings.png b/docs/_static/docs-mcp-client-settings.pngnew file mode 100644index 0000000000..ec0adbd8dcBinary files /dev/null and b/docs/_static/docs-mcp-client-settings.png differdiff --git a/docs/guides/editor_features/ai_completion.md b/docs/guides/editor_features/ai_completion.mdindex 90dc387dda..6494d4c047 100644--- a/docs/guides/editor_features/ai_completion.md+++ b/docs/guides/editor_features/ai_completion.md@@ -82,6 +82,11 @@ The chat panel on the left sidebar lets you chat with an LLM and ask questionsaboutyour notebook. The LLM can also generate code cells that you can insertinto your notebook.+The chat panel currently supports the following modes:++- **Ask**: Enables read-only [AI tools](tools.md) and [tools from added MCP Client servers](mcp.md#mcp-client) for context gathering, allowing the assistant to inspect your notebooks+- **Manual**: No tool access; the AI responds based only on the conversation and manually injected context+??? tip "See the chat panel in action"<iframe width="740" height="420" src="https://www.youtube.com/embed/4DC1E2UBwAM?si=zzrzl0VlvOU6JiZP" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>diff --git a/docs/guides/editor_features/mcp.md b/docs/guides/editor_features/mcp.mdnew file mode 100644index 0000000000..e9af131822--- /dev/null+++ b/docs/guides/editor_features/mcp.md@@ -0,0 +1,128 @@+# Model Context Protocol (MCP)++!!! warning "Experimental Feature"+ MCP features are currently experimental and under active development. Features and APIs may change.++marimo supports the Model Context Protocol (MCP) in two ways: as an [MCP server](mcp.md#mcp-server) that exposes marimo's [AI tools](tools.md) to external applications, and as an [MCP client](mcp.md#mcp-client) that connects [supported servers](mcp.md#supported-servers) to marimo's [chat panel](ai_completion.md#chat-panel).++## Prerequisites++Both MCP server and client features require the MCP dependencies. Run marimo with MCP support using one of the following methods:++/// tab | uv+```bash+# run with uv in a project+uv run --with="marimo[mcp]" marimo edit notebook.py --mcp --no-token+```+///++/// tab | uvx+```bash+# run with uvx anywhere+uvx "marimo[mcp]" edit notebook.py --mcp --no-token+```+///++/// tab | pip+```bash+# install with pip and a venv+pip install "marimo[mcp]"+marimo edit notebook.py --mcp --no-token+```+///++!!! note "Flags"+ The `--mcp` flag exposes an endpoint that provides access to your notebook data via the MCP server endpoint. Remove `--mcp` if you only want MCP Client features. The `--no-token` flag removes authentication, which should only be used for local development. Remove `--no-token` in production environments.++## MCP Server++marimo can expose its [AI tools](tools.md) through an MCP server endpoint, allowing external AI applications to interact with your notebooks.++### Available tools++When connected to marimo's MCP server, external applications can access all [AI tools](tools.md).++### Connecting external applications++marimo's MCP server works with any MCP-compatible application. Below are setup instructions for some commonly used applications:++!!! tip "Connection details"+ Replace `PORT` with your marimo server port in the examples below. If authentication is enabled, append `?access_token=YOUR_TOKEN` to the URL and replace `YOUR_TOKEN` with your marimo access token.++#### Claude Code++Use Claude Code's CLI to connect to marimo:++```bash+claude mcp add --transport http marimo http://localhost:PORT/mcp/server+```++#### Cursor++Configure Cursor to connect to marimo's MCP server:++```json+{+ "mcpServers": {+ "marimo": {+ "url": "http://localhost:PORT/mcp/server"+ }+ }+}+```++#### VS Code++Create a .vscode/mcp.json file in your workspace and configure it to connect to marimo's MCP server:++```json+{+ "servers": {+ "marimo": {+ "type": "http",+ "url": "http://localhost:PORT/mcp/server"+ }+ }+}+```++## MCP Client++marimo can connect to external MCP servers to add additional tools and context to the [chat panel](ai_completion.md#chat-panel).++### Supported servers++marimo currently supports the following MCP servers:++| Server | Description |+|--------|-------------|+| `marimo` | Provides marimo's official documentation, API reference, and code examples |+| `context7` | Fetches up-to-date, version-specific documentation and code examples from official sources |++### Configuration++Enable MCP client servers through the marimo settings UI:++<div align="center">+<figure>+<img src="/_static/docs-mcp-client-settings.png" width="740px"/>+<figcaption>Enable MCP servers in the AI settings panel.</figcaption>+</figure>+</div>++Alternatively, configure MCP servers in your marimo configuration file:++```toml title="marimo.toml"+[mcp]+presets = ["marimo", "context7"]+```++Once configured, tools from these servers will be automatically available in the [chat panel when using ask mode](ai_completion.md#chat-panel).++!!! info "Custom MCP servers"+ Support for custom MCP server configuration is not yet available.++## Related documentation++- [AI tools](tools.md) - Available tools exposed by the MCP server+- [AI-assisted coding](ai_completion.md#chat-panel) - Using the chat panel with MCP toolsdiff --git a/docs/guides/editor_features/tools.md b/docs/guides/editor_features/tools.mdnew file mode 100644index 0000000000..c3d145f592--- /dev/null+++ b/docs/guides/editor_features/tools.md@@ -0,0 +1,44 @@+# AI tools++!!! warning "Experimental Feature"+ Tools are currently experimental and under active development. Tool definitions and availability may change.++marimo exposes a set of tools that allow AI assistants to interact with your notebooks. These tools enable AI agents to read notebook content, inspect cell runtime data, access variables, handle errors, and more.++## Using tools++These tools are available when using the [chat panel in ask mode](ai_completion.md#chat-panel). External AI applications can also access these tools through the [marimo MCP server](mcp.md#mcp-server).++## Available tools++### Inspection++| Tool | Description |+|------|-------------|+| **get_active_notebooks** | List all currently active marimo notebooks. Returns summary statistics and notebook details including names, paths, and session IDs. Start here to discover which notebooks are available. |+| **get_lightweight_cell_map** | Get an overview of notebook structure showing a preview of each cell. Takes a `session_id` and optional `preview_lines` parameter. Returns cell IDs, preview text, line counts, and cell types (code, markdown, SQL). |+| **get_cell_runtime_data** | Get detailed runtime information for a specific cell. Takes `session_id` and `cell_id` parameters. Returns full cell code, error details, runtime metadata (execution time, runtime state), and variables defined by the cell. |++### Data++| Tool | Description |+|------|-------------|+| **get_tables_and_variables** | Get information about variables and data tables in a session. Takes `session_id` and `variable_names` parameters (empty list returns all). Returns table metadata (columns, primary keys, indexes, row counts) and variable values with data types. |+| **get_database_tables** | Get database schema information with optional query filtering. Takes `session_id` and optional `query` parameter (supports regex). Returns tables with connection name, database, schema, and table details. |++### Debugging++| Tool | Description |+|------|-------------|+| **get_notebook_errors** | Get all errors in the notebook organized by cell. Takes `session_id` parameter. Returns error summary (total errors, affected cells) and per-cell error details (type, message, traceback). |++### Reference++| Tool | Description |+|------|-------------|+| **get_marimo_rules** | Get official marimo guidelines and best practices for AI assistants. Returns the content of the marimo rules file and source URL for understanding marimo-specific conventions. |++## Related documentation++- [Model Context Protocol (MCP)]() - Learn how to expose tools through the marimo MCP server+- [AI-assisted coding](ai_completion.md) - Learn about more AI coding featuresdiff --git a/mkdocs.yml b/mkdocs.ymlindex def9b30a01..23cb23a227 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -131,6 +131,8 @@ nav:- Editor overview: guides/editor_features/overview.md- Understanding dataflow: guides/editor_features/dataflow.md- AI completion: guides/editor_features/ai_completion.md+ - Model Context Protocol: guides/editor_features/mcp.md+ - AI tools: guides/editor_features/tools.md- Agents: guides/editor_features/agents.md- Language Server: guides/editor_features/language_server.md- Package management: guides/editor_features/package_management.md