{"id":30867065,"url":"https://github.com/UsamaK98/python-notebook-mcp","last_synced_at":"2025-09-07T22:07:47.820Z","repository":{"id":284943737,"uuid":"956527563","full_name":"UsamaK98/python-notebook-mcp","owner":"UsamaK98","description":"Lightweight Python Notebook MCP - Enable AI assistants to create, edit, and view Jupyter notebooks via Model Context Protocol","archived":false,"fork":false,"pushed_at":"2025-04-30T15:54:38.000Z","size":388,"stargazers_count":31,"open_issues_count":1,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-22T05:34:55.114Z","etag":null,"topics":["ai-tools","claude","claude-desktop","cursor-ide","fastmcp","ipynb","jupyter","jupyter-notebooks","mcp","model-context-protocol","model-context-protocol-servers","notebook-editor","python","windsurf"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/UsamaK98.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-28T12:02:46.000Z","updated_at":"2025-06-21T20:07:58.000Z","dependencies_parsed_at":"2025-03-28T14:34:14.292Z","dependency_job_id":"7dcc1f9e-61c2-4dfb-be9e-cb3463918fc7","html_url":"https://github.com/UsamaK98/python-notebook-mcp","commit_stats":null,"previous_names":["usamak98/python-notebook-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/UsamaK98/python-notebook-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UsamaK98%2Fpython-notebook-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UsamaK98%2Fpython-notebook-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UsamaK98%2Fpython-notebook-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UsamaK98%2Fpython-notebook-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UsamaK98","download_url":"https://codeload.github.com/UsamaK98/python-notebook-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UsamaK98%2Fpython-notebook-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274101817,"owners_count":25222452,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","claude","claude-desktop","cursor-ide","fastmcp","ipynb","jupyter","jupyter-notebooks","mcp","model-context-protocol","model-context-protocol-servers","notebook-editor","python","windsurf"],"created_at":"2025-09-07T22:03:24.078Z","updated_at":"2025-09-07T22:07:47.805Z","avatar_url":"https://github.com/UsamaK98.png","language":"Python","funding_links":[],"categories":["📚 Projects (1974 total)","🤖 AI/ML","Code Execution \u0026 Automation Mcp Servers"],"sub_categories":["MCP Servers"],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003ePython Notebook MCP\u003c/h1\u003e\n  \u003cp\u003eMCP server enabling AI assistants to interact with Jupyter notebooks through the Model Context Protocol.\u003c/p\u003e\n  \u003cp\u003e\n    \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"MIT License\"/\u003e\u003c/a\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Python-3.10+-blue.svg\" alt=\"Python 3.10+\"/\u003e\n    \u003cimg src=\"https://img.shields.io/badge/MCP-Compatible-orange.svg\" alt=\"MCP Compatible\"/\u003e\n    \u003ca href=\"https://mseep.ai/app/286d0c4c-dcec-477b-bc2c-b20d2ce85ef2\"\u003e\u003cimg src=\"https://mseep.ai/badge.svg\" alt=\"Verified on MseeP\"/\u003e\u003c/a\u003e\n    \u003ca href=\"CodeRabbit Pull Request Reviews\"\u003e\u003cimg src=\"https://img.shields.io/coderabbit/prs/github/UsamaK98/python-notebook-mcp?utm_source=oss\u0026utm_medium=github\u0026utm_campaign=UsamaK98%2Fpython-notebook-mcp\u0026labelColor=171717\u0026color=FF570A\u0026link=https%3A%2F%2Fcoderabbit.ai\u0026label=CodeRabbit+Reviews\"/\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\u003cdiv align=\"center\"\u003e\n\u003ca href=\"https://mseep.ai/app/usamak98-python-notebook-mcp\"\u003e\u003cimg src=\"https://mseep.net/pr/usamak98-python-notebook-mcp-badge.png\" alt=\"MseeP.ai Security Assessment Badge\"/\u003e\u003c/a\u003e \n\u003c/div\u003e\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 \u0026 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    \u003e **❓ 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    \u003e **⚠️ 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\u003e ⚠️ 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 \u0026 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. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FUsamaK98%2Fpython-notebook-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FUsamaK98%2Fpython-notebook-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FUsamaK98%2Fpython-notebook-mcp/lists"}