Create notebook tool call

[nojaf]

📝 Summary

Adds a new MCP tool create_notebook that allows AI assistants to create new marimo notebooks via the MCP server.

🔍 Description of Changes

Motivation

When using marimo with an AI assistant (like Claude) via MCP, there was no way to programmatically create new notebooks. Users had to manually create files or use marimo new separately. This PR enables a workflow where you can tell an AI assistant "create a new notebook that does X" and have it create the file, ready to open.

Changes

New MCP Tool: create_notebook

• Location: marimo/_ai/_tools/tools/create_notebook.py
• Arguments:
  • filename (required): Name for the new notebook (e.g., analysis.py)
  • prompt (optional): If provided, attempts to generate initial content via marimo's AI API
• Returns: file_path and url to open the notebook in the browser

Key Features:

1. AI-powered content generation: When a prompt is provided and the user has accepted marimo's AI terms, calls https://ai.marimo.app/api/notebook.py to generate initial notebook content
2. Validation: Uses the same linting engine as marimo check to validate generated content before writing (checks linter.errored and linter.issues_count)
3. Graceful fallback: If AI is unavailable or validation fails, creates a minimal valid notebook with the prompt as a comment
4. Auto-suffix on collision: If analysis.py exists, creates analysis_1.py, analysis_2.py, etc.
5. Works in both modes:
   • Directory mode (marimo edit .): Creates in served directory, calls mark_stale() on router
   • Single-file mode (marimo edit notebook.py): Creates sibling file, calls register_allowed_file()

Files Changed:

• marimo/_ai/_tools/tools/create_notebook.py (new)
• marimo/_ai/_tools/tools_registry.py (added to tool list)
• tests/_ai/tools/tools/test_create_notebook.py (new, 20 tests)

Usage

# Start marimo with MCP enabled
marimo edit --mcp --no-token .

# Add MCP server to Claude Code
claude mcp add --transport http marimo http://localhost:2718/mcp/server --scope local

Then ask Claude: "Create a new notebook called data_analysis.py that visualizes some sample data"

📋 Checklist

• I have read the contributor guidelines.
• For large changes, or changes that affect the public API: this change was discussed or approved through an issue, on Discord, or the community discussions (Please provide a link if applicable).
• Tests have been added for the changes made.
• Documentation has been updated where applicable, including docstrings for API changes.
• Pull request title is a good summary of the changes - it will be used in the release notes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview, Comment	Feb 9, 2026 10:42am

[Light2Dark]

Hey @nojaf, thanks for the feature. We've seen some work by folks who have made this a skill instead (create-marimo-notebook-skill). So, just wondering if there's anything special a tool can do that a skill / good prompt can't?
Or is the creation of notebooks from a prompt subpar? Should we improve the prompt or CLAUDE.md

[nojaf]

Hey @Light2Dark, great question! A skill could use marimo new to create a notebook, but the key limitation is what happens after creation.

My use case: I run marimo edit --mcp --watch --no-token and connect one or more Claude instances to that MCP server. I want to ask Claude things like "what alphas are owned by team Y" and have it:

1. Create a notebook to investigate the question
2. Write code to query our internal systems
3. Iterate on the code until it gets the answer
4. Return the answer to me

With a skill using marimo new, Claude could create the notebook, but then it has no way to interact with it - it can't use the existing MCP inspection tools (get_cell_outputs, get_lightweight_cell_map, etc.) because those require a session_id from an active notebook. The notebook would just open in a browser and Claude would be stuck.

Why notebooks instead of scripts:

• Iterative execution: A Python script requires re-running everything on each failed step, repeatedly hitting internal systems (unreliable and expensive). A notebook lets the agent iterate cell-by-cell without redoing prior work.
• Inspectable artifacts: If an answer looks suspicious, I can open the notebook and inspect the debugging cells. A script doesn't give me that.
• Reusable outputs: "Write a dashboard that reports on X and push it to repo Y" - the notebook becomes a permanent artifact.

The goal is for Claude to have an introspectable interactive Python session it can work with autonomously. Ideally I never need to open the browser - Claude iterates, gets the answer, and reports back. I only check the notebook manually if something seems off.

What we have now: This PR adds create_notebook which creates the file and registers it with the router.

What's still needed: For the full workflow to work without manual intervention, we'd also need:

• A way to start a notebook (create a session programmatically so the existing inspection tools like get_cell_outputs can interact with it)
• A way to stop a notebook (close the session when done)

Looking at the codebase, session_manager.create_session() requires a SessionConsumer. Currently sessions are only created via WebSocket connections from the browser. Would you be open to a HeadlessSessionConsumer concept that allows creating sessions server-side for MCP-driven workflows?

Happy to scope this PR to just file creation as a first step, or expand it to include session management - whatever fits better with your roadmap.

[Light2Dark]

Got it thanks. Looping in @dmadisetti since he tried the skills approach. There is a get_active_notebooks tool which you can use. I imagined AI can write the notebook, manually run it (using uv etc) and close it as well. But you're probably right about the browserless execution flow.

[nojaf]

Hi @Light2Dark , I talked about this PR with @mscolnick last week.
One outcome was that the mcp tool should not create the notebook.
There is either marimo new or an LLM can just write a Python file.
So, I refactored the code have a start_session instead.

Let me know if that works.

[github-actions]

This pull request has been automatically marked as stale because it has not had activity in 30 days. It will be closed in 14 days if no further activity occurs. If this PR is still relevant, please leave a comment or push new changes to keep it open. Thank you for your contribution!

[nojaf]

Yes, this PR is still relevant. I'm still hoping to get a reaction from the team here.

[dmadisetti]

Looping in @manzt since marimo-pair can connect to multiple sessions. I think just through a bit of prompt engineering this might already be possible

[nojaf]

Thanks @dmadisetti for pointing me to marimo-pair, I was able to do it but my LLM got quite confused.

It gave me some feedback:

  The skill has no guidance for creating new notebooks in folder mode.                                                                         
                                                                                                                                   
  The skill docs cover discovering servers, executing code, and mutating cells via code_mode — but all of that assumes a session already       
  exists. When marimo runs in folder mode (marimo edit ./books), there's no active session until the user opens a notebook in the browser.   
                                                                                                                                               
  The gap I hit:                                                                                                                               
  1. discover-servers.sh found the server on 2719, but execute-code.sh failed with "No active sessions."                                       
  2. The skill says "If there's no .py file yet, pick a descriptive filename" and start marimo — but marimo was already running. I couldn't    
  start a second instance on the same port.                                                                                                    
  3. My first instinct was to write the .py file directly, but the skill explicitly says "NEVER write to the .py file directly while a session 
  is running." Even though no session was active yet, the server owned that directory.                                                         
  4. I had to dig through marimo's server source code to find the /api/files/create endpoint with type: "notebook" — that's not documented     
  anywhere in the skill.                                                                                                                       
                                                                                                                                               
  Suggestions for the skill:                                                                                                                   
  - Document the folder-mode workflow: how to create a new notebook via the API (POST /api/files/create with type: "notebook"), and that the   
  user then needs to open it from the browser before code_mode works.                                                                          
  - Clarify that "no active sessions" ≠ "server not running" — in folder mode it's the expected state until a notebook is opened.            
  - Consider adding a create-notebook.sh script alongside discover-servers.sh and execute-code.sh. 

@manzt want me to create an issue for that over at marimo-pair?

[nojaf]

Happy to close this in favour of marimo-pair.

[manzt]

Thanks @nojaf. Yeah feel free to open an issue in pair!