[{"_1":2,"_228":-5,"_229":-5},"loaderData",{"_3":4,"_20":21,"_22":23,"_181":182},"root",{"_5":6,"_7":8},"toasts",[],"visitor",{"_9":10,"_11":12},"viewportWidth",1280,"visitorSession",{"_13":14,"_16":-5,"_17":18,"_19":-5},"attributes",[15],"BOT","membership","uid","71CMQLGCs9","userAccount","routes/_public/_layout",{},"routes/_public/mcp/servers/~namespace/~slug/_pages/_layout",{"_24":25,"_26":-5,"_27":28,"_29":39,"_98":99,"_180":78},"availableLocales",[],"githubUser","locale",{"_29":30,"_33":36,"_37":38},"mcpServer",{"_31":32,"_33":32,"_34":35},"description","Python notebook mcp","name","readme","

Python Notebook MCP

MCP server enabling AI assistants to interact with Jupyter notebooks through the Model Context Protocol.

\n $\"MIT$ \n $\"Python$ \n $\"MCP$ \n

\n\nThis server allows compatible AI assistants (like Cursor or Claude Desktop) to interact with Jupyter Notebook files (.ipynb) on your local machine.\n\n## 📋 Prerequisites\n\nBefore you begin, ensure you have the following installed:\n\n1. **Python:** Version 3.10 or higher.\n2. **`uv`:** The fast Python package installer and virtual environment manager from Astral. If you don't have it, install it:\n ```bash\n # On macOS / Linux\n curl -LsSf https://astral.sh/uv/install.sh | sh\n\n # On Windows (PowerShell)\n powershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n\n # IMPORTANT: Add uv to your PATH if prompted by the installer\n # For macOS/Linux (bash/zsh), add to your ~/.zshrc or ~/.bashrc:\n # export PATH=\"$HOME/.local/bin:$PATH\"\n # Then restart your shell or run `source ~/.zshrc` (or equivalent)\n ```\n3. **`fastmcp` CLI (Optional, for Claude Desktop `fastmcp install`):** If you plan to use the `fastmcp install` method for Claude Desktop, you need the `fastmcp` command available.\n ```bash\n # Using uv\n uv pip install fastmcp\n\n # Or using pipx (recommended for CLI tools)\n pipx install fastmcp\n ```\n\n## 🔧 Setup\n\n1. **Clone the Repository:**\n ```bash\n git clone https://github.com/UsamaK98/python-notebook-mcp.git # Or your fork/local path\n cd python-notebook-mcp\n ```\n\n2. **Choose Setup Method:**\n\n * **Option A: Automated Setup (Recommended)**\n Run the appropriate script for your OS from the project's root directory (where you just `cd`-ed into).\n * **macOS / Linux:**\n ```bash\n # Make script executable (if needed)\n chmod +x ./install_unix.sh\n # Run the script\n bash ./install_unix.sh\n ```\n * **Windows (PowerShell):**\n ```powershell\n # You might need to adjust PowerShell execution policy first\n # Set-ExecutionPolicy RemoteSigned -Scope CurrentUser\n .\\install_windows.ps1\n ```\n These scripts will create the `.venv`, install dependencies, and output the exact paths needed for your MCP client configuration.\n\n * **Option B: Manual Setup**\n Follow these steps if you prefer manual control or encounter issues with the scripts.\n 1. **Create & Activate Virtual Environment:**\n ```bash\n # Create the environment (e.g., named .venv)\n uv venv\n\n # Activate the environment\n # On macOS/Linux (bash/zsh):\n source .venv/bin/activate\n # On Windows (Command Prompt):\n # .venv\\Scripts\\activate.bat\n # On Windows (PowerShell):\n # .venv\\Scripts\\Activate.ps1\n ```\n *(You should see `(.venv)` or similar at the start of your shell prompt)*\n 2. **Install Dependencies:**\n ```bash\n # Make sure your venv is active\n uv pip install -r requirements.txt\n ```\n\n## ▶️ Running the Server\n\nMake sure your virtual environment (`.venv`) is activated if you used manual setup.\n\n### Method 1: Direct Execution (Recommended for Cursor, General Use)\n\nThis method uses `uv run` to execute the server script directly using your current Python environment (which should now have the dependencies installed).\n\n1. **Run the Server:**\n ```bash\n # From the python-notebook-mcp directory\n uv run python server.py\n ```\n The server will start and print status messages, including the (uninitialized) workspace directory.\n\n2. **Client Configuration (`mcp.json`):** Configure your MCP client (e.g., Cursor) to connect. Create or edit the client's MCP configuration file (e.g., `.cursor/mcp.json` in your workspace).\n\n **Template (Recommended):**\n ```json\n {\n \"mcpServers\": {\n \"jupyter\": {\n // Use the absolute path to the Python executable inside your .venv\n \"command\": \"/full/absolute/path/to/python-notebook-mcp/.venv/bin/python\", // macOS/Linux\n // \"command\": \"C:\\\\full\\\\absolute\\\\path\\\\to\\\\python-notebook-mcp\\\\.venv\\\\Scripts\\\\python.exe\", // Windows\n \"args\": [\n // Absolute path to the server script\n \"/full/absolute/path/to/python-notebook-mcp/server.py\"\n ],\n \"autoApprove\": [\"initialize_workspace\"] // Optional: Auto-approve certain safe tools\n }\n }\n }\n ```\n > **❓ Why the full path to Python?** GUI applications like Cursor might not inherit the same `PATH` environment as your terminal. Specifying the exact path to the Python interpreter inside your `.venv` ensures the server runs with the correct environment and dependencies.\n > **⚠️ IMPORTANT:** Replace the placeholder paths with the actual **absolute paths** on your system.\n\n### Method 2: Claude Desktop Integration (`fastmcp install`)\n\nThis method uses the `fastmcp` tool to create a dedicated, isolated environment for the server and register it with Claude Desktop. You generally don't need to activate the `.venv` manually for this method, as `fastmcp install` handles environment creation.\n\n1. **Install the Server for Claude:**\n ```bash\n # From the python-notebook-mcp directory\n fastmcp install server.py --name \"Jupyter Notebook MCP\"\n ```\n * `fastmcp install` uses `uv` behind the scenes to create the environment and install dependencies from `requirements.txt`.\n * The server will now appear in the Claude Desktop developer settings and can be enabled there. You generally *don't* need to manually edit `claude_desktop_config.json` when using `fastmcp install`.\n\n## 📘 Usage\n\n### Key Concept: Workspace Initialization\n\nRegardless of how you run the server, the **first action** you *must* take from your AI assistant is to initialize the workspace. This tells the server where your project files and notebooks are located.\n\n```python\n# Example tool call from the client (syntax may vary)\ninitialize_workspace(directory=\"/full/absolute/path/to/your/project_folder\")\n```\n\n> ⚠️ You **must** provide the full **absolute path** to the directory containing your notebooks. Relative paths or paths like `.` are not accepted. The server will confirm the path and list any existing notebooks found.\n\n### Core Operations\n\nOnce the workspace is initialized, you can use the available tools:\n\n```python\n# List notebooks\nlist_notebooks()\n\n# Create a new notebook\ncreate_notebook(filepath=\"analysis/new_analysis.ipynb\", title=\"My New Analysis\")\n\n# Add a code cell to the notebook\nadd_cell(filepath=\"analysis/new_analysis.ipynb\", content=\"import pandas as pd\\ndf = pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})\\ndf.head()\", cell_type=\"code\")\n\n# Read the first cell (index 0)\nread_cell(filepath=\"analysis/new_analysis.ipynb\", cell_index=0)\n\n# Edit the second cell (index 1)\nedit_cell(filepath=\"analysis/new_analysis.ipynb\", cell_index=1, content=\"# This is updated markdown\")\n\n# Read the output of the second cell (index 1) after execution (if any)\nread_cell_output(filepath=\"analysis/new_analysis.ipynb\", cell_index=1)\n\n# Read the entire notebook structure\nread_notebook(filepath=\"analysis/new_analysis.ipynb\")\n```\n\n## 🛠️ Available Tools\n\n| Tool | Description |\n| :----------------------- | :----------------------------------------------------------------- |\n| `initialize_workspace` | **REQUIRED FIRST STEP.** Sets the absolute path for the workspace. |\n| `list_notebooks` | Lists all `.ipynb` files found within the workspace directory. |\n| `create_notebook` | Creates a new, empty Jupyter notebook if it doesn't exist. |\n| `read_notebook` | Reads the entire structure and content of a notebook. |\n| `read_cell` | Reads the content and metadata of a specific cell by index. |\n| `edit_cell` | Modifies the source content of an existing cell by index. |\n| `add_cell` | Adds a new code or markdown cell at a specific index or the end. |\n| `read_notebook_outputs` | Reads all outputs from all code cells in a notebook. |\n| `read_cell_output` | Reads the output(s) of a specific code cell by index. |\n\n## 🧪 Development & Debugging\n\nIf you need to debug the server itself:\n\n* **Run Directly:** Use `uv run python server.py` and observe the terminal output for errors or print statements.\n* **FastMCP Dev Mode:** For interactive testing with the MCP Inspector:\n ```bash\n # Make sure fastmcp is installed in your environment\n # uv pip install fastmcp\n uv run fastmcp dev server.py\n ```\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ","English","tag","en-US",{"_40":41,"_42":-5,"_13":43,"_45":32,"_46":32,"_47":48,"_51":52,"_74":-5,"_75":76,"_77":78,"_79":80,"_33":32,"_81":65,"_82":-5,"_83":-5,"_84":-5,"_85":-5,"_86":87,"_91":-5,"_92":61,"_93":-5,"_94":-5,"_17":95,"_96":97},"addedAt",["D",1745283035482],"argumentsJsonSchema",[44],"language:python","descriptionMarkdown","descriptionPlainText","githubProject",{"_34":35,"_49":50},"url","https://github.com/UsamaK98/python-notebook-mcp","githubRepository",{"_53":54,"_55":56,"_57":58,"_59":60,"_33":61,"_62":63,"_67":68,"_69":70,"_72":73},"defaultBranch","main","fullName","UsamaK98/python-notebook-mcp","githubTreeId",109591,"language","Python","python-notebook-mcp","owner",{"_64":65,"_17":66},"login","UsamaK98","eCMzUYKnll","recentStargazers",0,"spdxLicense",{"_33":71},"MIT License","stargazers",13,"glamaJson","id",5792,"inspectable",false,"integrations",[],"namespace","npmPackage","prompts","redditPostForeignId","resources","scores",{"_88":-5,"_89":-5,"_90":-5},"license","quality","security","simpleIcon","slug","supportedPlatforms","tools","6fqxax1kui","updatedAt",["D",1745283047622],"meta",[100,103,105,112,115,117,120,123,126,129,132,134,137,140,142,144,146,148,150],{"_101":102},"title","Python notebook mcp | Glama",{"_104":32,"_33":31},"content",{"_106":107,"_108":109,"_110":111},"href","https://glama.ai/mcp/servers/@UsamaK98/python-notebook-mcp","rel","canonical","tagName","link",{"_104":32,"_113":114},"property","og:title",{"_104":32,"_113":116},"og:description",{"_104":118,"_113":119},"https://glama.ai/logo.png","og:logo",{"_104":121,"_113":122},"https://glama.ai/mcp/servers/@UsamaK98/python-notebook-mcp/og-image","og:image",{"_104":124,"_113":125},"630","og:image:height",{"_104":127,"_113":128},"1200","og:image:width",{"_104":130,"_113":131},"website","og:type",{"_104":107,"_113":133},"og:url",{"_104":135,"_113":136},"ChatGPT alternative for power users","og:site_name",{"_104":138,"_33":139},"summary_large_image","twitter:card",{"_104":135,"_33":141},"twitter:title",{"_104":32,"_33":143},"twitter:description",{"_104":121,"_33":145},"twitter:image",{"_104":124,"_33":147},"twitter:image:height",{"_104":127,"_33":149},"twitter:image:width",{"_151":152},"script:ld+json",{"_153":154,"_155":156},"@context","http://schema.org","@graph",[157],{"_153":158,"_159":160,"_161":162},"https://schema.org","@type","BreadcrumbList","itemListElement",[163,170,174,178],{"_159":164,"_165":166,"_33":167,"_168":169},"ListItem","item","https://glama.ai/","Glama","position",1,{"_159":164,"_165":171,"_33":172,"_168":173},"https://glama.ai/mcp","MCP",2,{"_159":164,"_165":175,"_33":176,"_168":177},"https://glama.ai/mcp/servers","Servers",3,{"_159":164,"_165":107,"_33":32,"_168":179},4,"visitorIsMaintainer","routes/_public/mcp/servers/~namespace/~slug/_pages/reviews/_route",{"_26":-5,"_29":183,"_98":193,"_227":-5},{"_40":184,"_42":-5,"_13":185,"_45":32,"_46":32,"_47":186,"_51":187,"_74":-5,"_75":76,"_77":78,"_79":190,"_33":32,"_81":65,"_82":-5,"_83":-5,"_84":-5,"_85":-5,"_86":191,"_91":-5,"_92":61,"_93":-5,"_94":-5,"_17":95,"_96":192},["D",1745283035482],[44],{"_34":35,"_49":50},{"_53":54,"_55":56,"_57":58,"_59":60,"_33":61,"_62":188,"_67":68,"_69":189,"_72":73},{"_64":65,"_17":66},{"_33":71},[],{"_88":-5,"_89":-5,"_90":-5},["D",1745283047622],[194,196,197,199,201,202,203,204,205,206,207,208,209,210,211,212,213,214,215],{"_101":195},"Reviews | Python notebook mcp | Glama",{"_104":32,"_33":31},{"_106":198,"_108":109,"_110":111},"https://glama.ai/mcp/servers/@UsamaK98/python-notebook-mcp/reviews",{"_104":200,"_113":114},"Reviews | Python notebook mcp",{"_104":32,"_113":116},{"_104":118,"_113":119},{"_104":121,"_113":122},{"_104":124,"_113":125},{"_104":127,"_113":128},{"_104":130,"_113":131},{"_104":198,"_113":133},{"_104":135,"_113":136},{"_104":138,"_33":139},{"_104":135,"_33":141},{"_104":32,"_33":143},{"_104":121,"_33":145},{"_104":124,"_33":147},{"_104":127,"_33":149},{"_151":216},{"_153":154,"_155":217},[218],{"_153":158,"_159":160,"_161":219},[220,221,222,223,224],{"_159":164,"_165":166,"_33":167,"_168":169},{"_159":164,"_165":171,"_33":172,"_168":173},{"_159":164,"_165":175,"_33":176,"_168":177},{"_159":164,"_165":107,"_33":32,"_168":179},{"_159":164,"_165":198,"_33":225,"_168":226},"Reviews",5,"review","actionData","errors"]

Rate & Review