You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit a28d2e5
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/deepnote-mcp.md
+58-8Lines changed: 58 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,7 @@ noContent: false
9
9
10
10
The **Deepnote MCP server** exposes your Deepnote workspace to AI agents through the Model Context Protocol (MCP), an open standard for connecting LLMs to external tools and data.
11
11
12
-
Once connected, agentic harnesses and IDEs such as Codex, Claude, Cursor, VS Code, or any MCP-compatible client can explore your projects, read, create, edit, and run notebooks, inspect your data integrations, and search Deepnote's documentation within your existing permissions.
12
+
Once connected, agentic harnesses and IDEs such as Codex, Claude, Cursor, VS Code, or any MCP-compatible client can explore your projects, read, create, edit, run, and delete notebooks, manage project files and machines, publish apps, inspect your data integrations, and search Deepnote's documentation within your existing permissions.
13
13
14
14
This means you can ask your assistant to "create a notebook in my analytics project and add a SQL block that queries last month's revenue", and it will use the Deepnote MCP tools to carry out each step.
15
15
@@ -45,27 +45,64 @@ The server exposes the following tools. Read-only tools never modify your worksp
45
45
46
46
### Account and workspace
47
47
48
-
-`get_me`: Return info about the authenticated individual: the workspace, the access level (viewer, editor, admin), etc.
48
+
-`get_me`: Return info about the API key or account calling the server: the key name and type, who created it, the workspace, and the access level (viewer, editor, admin, etc.).
49
49
-`search`: Search workspace resources across projects, notebooks, blocks, and integrations.
50
-
-`list_projects`: List workspace projects.
51
-
-`create_project`: Create a new project.
50
+
-`list_projects`: List workspace projects, optionally filtered by name.
51
+
-`list_folders`: List workspace folders and how they nest, so an agent can turn a folder name or path into the folder ID that `create_project` accepts.
52
+
-`get_project`: Get a project's metadata, notebooks, attached integrations, files, static website settings, and environment.
53
+
-`create_project`: Create a new project, optionally inside a folder and on a chosen environment.
54
+
-`update_project`: Change a project's environment, its static website sharing and viewer API access, and whether its Streamlit apps may call the Deepnote API as their viewers. Changing the environment restarts a running machine.
55
+
-`delete_project`: Move a project and all its notebooks to the workspace trash.
52
56
53
57
### Notebooks and blocks
54
58
55
59
-`get_notebook`: Get notebook details, including its blocks and input variables.
56
60
-`create_notebook`: Create an empty notebook inside a project.
57
-
-`create_block`: Create a new block (SQL, Python, text, etc.) in a notebook.
61
+
-`update_notebook`: Rename a notebook. Naming it `Init` turns it into the project's [init notebook](/docs/project-initialization).
62
+
-`duplicate_notebook`: Duplicate an existing notebook within a project.
63
+
-`delete_notebook`: Delete a notebook. A project version is saved first, so you can restore it from version history.
64
+
-`get_block`: Get a block's content and metadata, and optionally the outputs it shows in the editor.
65
+
-`create_block`: Create a new block (SQL, Python, text, input, etc.) in a notebook.
58
66
-`update_block`: Update the contents of an existing block.
67
+
-`delete_block`: Delete a block from a notebook.
59
68
-`reorder_notebook_blocks`: Move one or more blocks to a new position within a notebook.
60
-
-`duplicate_notebook`: Duplicate an existing notebook within a project.
61
69
-`generate_project_url`: Generate a link to a Deepnote project or notebook, so an agent can hand you a URL to what it built.
62
70
71
+
### Files
72
+
73
+
-`write_file`: Write text or base64 content to a file in a project, with the path relative to the project root. With `overwrite` set it replaces an existing file; otherwise Deepnote picks a unique path and returns it.
74
+
-`copy_file`: Copy a file into another project at the same path.
75
+
-`delete_file`: Permanently delete a file from a project. A Streamlit app that uses the file as its entry point is deleted with it.
76
+
63
77
### Running notebooks
64
78
65
-
-`create_run`: Start running a notebook and return the created run.
66
-
-`get_run`: Get a notebook run. Returns a presigned snapshot download URL when available, or optionally the inline snapshot content.
79
+
-`create_run`: Start running a notebook and return the created run. Runs are detached by default and can use a different machine type than the project's; set `detached` to false for live mode or to run specific blocks.
80
+
-`get_run`: Get a notebook run. Returns a presigned snapshot download URL when available, or optionally the inline snapshot content or the executed blocks with their outputs. Large outputs are shortened unless `fullOutputs` is set.
67
81
-`list_notebook_runs`: List historical runs for a notebook.
68
82
83
+
### Machines and environments
84
+
85
+
-`get_machine`: Check whether a project's machine is stopped, starting, running, stopping, or in an error state, along with its machine type and sandbox environment.
86
+
-`start_machine`: Start a project's machine. It uses machine time until it stops.
87
+
-`stop_machine`: Stop a project's machine. Project files are kept, but kernel state such as variables is lost for everyone in the project.
88
+
-`restart_machine`: Replace a project's machine with a new one, which also recovers a machine in an error state. Kernel state is lost.
89
+
-`update_machine`: Change a project's machine type, sandbox environment, or how long it keeps running without activity. Changing the type or sandbox environment of a running machine needs a restart.
90
+
-`list_machine_types`: List the machine types the workspace can use, with their vCPUs, memory, and GPUs, and whether the plan and this month's free quota allow each one.
91
+
-`list_environments`: List the environments (Docker images) projects can run on, including the workspace's custom images.
92
+
93
+
These tools manage the machine behind the editor, live-mode runs, and hosted Streamlit apps. Detached runs start machines of their own, so an agent doesn't need to start the project's machine before calling `create_run`.
94
+
95
+
### Apps and static sites
96
+
97
+
-`create_streamlit_app`: Serve a project file as a [Streamlit app](/docs/streamlit) and return its URL.
98
+
-`list_streamlit_apps`: List a project's Streamlit apps with the file each one runs and its URL.
99
+
-`get_streamlit_app_status`: Check whether a Streamlit app is running, starting, or unavailable.
100
+
-`publish_static_site`: Publish a small HTML, CSS, and JavaScript site from the project's `_deepnote_static/` folder and share it as an app. For larger sites, use [`deepnote publish`](/docs/deepnote-cli-publish) from the CLI.
101
+
102
+
<Calloutstatus="warning">
103
+
Creating a Streamlit app with `create_streamlit_app` restarts the project machine and interrupts anyone working in the project.
104
+
</Callout>
105
+
69
106
### Integrations
70
107
71
108
-`list_integrations`: List workspace integrations, optionally filtered by name or type.
@@ -82,6 +119,18 @@ The server exposes the following tools. Read-only tools never modify your worksp
82
119
-`list_docs`: Return the Deepnote docs navigation tree so the assistant can find the right article.
83
120
-`get_doc`: Fetch the full Markdown body of a documentation article by slug.
84
121
122
+
### What deleting does
123
+
124
+
Deleting a project, a notebook, or a file works differently once it has run, so it helps to know which ones can be undone.
125
+
126
+
Deleting a notebook with `delete_notebook` saves a project version first. You can bring the notebook back from [version history](/docs/history).
127
+
128
+
Deleting a project with `delete_project` moves it to the [trash](/docs/trash), where you can restore it for 30 days. Its schedules are removed and don't come back with a restore, and its machine is stopped.
129
+
130
+
<Calloutstatus="warning">
131
+
Deleting a file with `delete_file` can't be undone in Deepnote, since project files aren't versioned. The same applies to the old content when `write_file` overwrites a file.
132
+
</Callout>
133
+
85
134
## Connecting a client
86
135
87
136
The examples below assume you have created a workspace API key under **Settings & members > Security > API keys**.
@@ -177,6 +226,7 @@ Because the assistant can chain tools together, a single natural-language reques
177
226
-**Run and inspect:** “Run the Monthly KPIs notebook and tell me what changed.” → `create_run` → `get_run`
-**Tidy a notebook:** “Move the imports block to the top and replace the empty scratch block with a note.” → `get_notebook` → `reorder_notebook_blocks` → `update_block`
229
+
-**Clean up a project:** “Delete the scratch notebook in the Q3 forecast project.” → `list_projects` → `get_project` → `delete_notebook`
180
230
-**Answer product questions:** “How do I schedule a notebook?” → `list_docs` → `get_doc`
0 commit comments