Python Notebook MCP

Permite que los asistentes de IA interactúen con cuadernos Jupyter locales (.ipynb).

Documentación

Python Notebook MCP

Servidor MCP que permite a los asistentes de IA interactuar con notebooks de Jupyter a través del Model Context Protocol.

Este servidor permite que asistentes de IA compatibles (como Cursor o Claude Desktop) interactúen con archivos de Jupyter Notebook (.ipynb) en tu máquina local.

📋 Requisitos previos

Antes de comenzar, asegúrate de tener instalado lo siguiente:

Python: Versión 3.10 o superior.

uv: El instalador rápido de paquetes de Python y gestor de entornos virtuales de Astral. Si no lo tienes, instálalo:

# On macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# IMPORTANT: Add uv to your PATH if prompted by the installer
# For macOS/Linux (bash/zsh), add to your ~/.zshrc or ~/.bashrc:
# export PATH="$HOME/.local/bin:$PATH"
# Then restart your shell or run `source ~/.zshrc` (or equivalent)

fastmcp CLI (Opcional, para fastmcp install de Claude Desktop): Si planeas usar el método fastmcp install para Claude Desktop, necesitas tener disponible el comando fastmcp.
```
# Using uv
uv pip install fastmcp

# Or using pipx (recommended for CLI tools)
pipx install fastmcp
```

🔧 Configuración

Clona el repositorio:

git clone https://github.com/UsamaK98/python-notebook-mcp.git # Or your fork/local path
cd python-notebook-mcp

Elige el método de configuración:
- Opción A: Configuración automatizada (Recomendada) Ejecuta el script apropiado para tu sistema operativo desde el directorio raíz del proyecto (donde acabas de hacer cd).
  - macOS / Linux:
```
# Make script executable (if needed)
chmod +x ./install_unix.sh
# Run the script
bash ./install_unix.sh
```
  - Windows (PowerShell):
```
# You might need to adjust PowerShell execution policy first
# Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
.\install_windows.ps1
```
  Estos scripts crearán el .venv, instalarán las dependencias y mostrarán las rutas exactas necesarias para la configuración de tu cliente MCP.
- Opción B: Configuración manual Sigue estos pasos si prefieres el control manual o encuentras problemas con los scripts.
  1. Crea y activa el entorno virtual:
```
# Create the environment (e.g., named .venv)
uv venv

# Activate the environment
# On macOS/Linux (bash/zsh):
source .venv/bin/activate
# On Windows (Command Prompt):
# .venv\Scripts\activate.bat
# On Windows (PowerShell):
# .venv\Scripts\Activate.ps1
```
    (Deberías ver (.venv) o algo similar al inicio del prompt de tu shell)
  2. Instala las dependencias:
```
# Make sure your venv is active
uv pip install -r requirements.txt
```

▶️ Ejecutando el servidor

Asegúrate de que tu entorno virtual (.venv) esté activado si usaste la configuración manual.

Método 1: Ejecución directa (Recomendado para Cursor, uso general)

Este método usa uv run para ejecutar el script del servidor directamente usando tu entorno de Python actual (que ahora debería tener las dependencias instaladas).

Ejecuta el servidor:
```
# From the python-notebook-mcp directory
uv run python server.py
```
El servidor se iniciará y mostrará mensajes de estado, incluido el directorio de trabajo (sin inicializar).
Configuración del cliente (mcp.json): Configura tu cliente MCP (por ejemplo, Cursor) para conectarse. Crea o edita el archivo de configuración MCP del cliente (por ejemplo, .cursor/mcp.json en tu espacio de trabajo).

Plantilla (Recomendada):
```
{
  "mcpServers": {
    "jupyter": {
      // Use the absolute path to the Python executable inside your .venv
      "command": "/full/absolute/path/to/python-notebook-mcp/.venv/bin/python", // macOS/Linux
      // "command": "C:\\full\\absolute\\path\\to\\python-notebook-mcp\\.venv\\Scripts\\python.exe", // Windows
      "args": [
          // Absolute path to the server script
          "/full/absolute/path/to/python-notebook-mcp/server.py"
        ],
      "autoApprove": ["initialize_workspace"] // Optional: Auto-approve certain safe tools
    }
  }
}
```
❓ ¿Por qué la ruta completa a Python? Las aplicaciones GUI como Cursor podrían no heredar el mismo entorno PATH que tu terminal. Especificar la ruta exacta al intérprete de Python dentro de tu .venv garantiza que el servidor se ejecute con el entorno y las dependencias correctos. ⚠️ IMPORTANTE: Reemplaza las rutas de ejemplo con las rutas absolutas reales de tu sistema.

Método 2: Integración con Claude Desktop (`fastmcp install`)

Este método usa la herramienta fastmcp para crear un entorno dedicado y aislado para el servidor y registrarlo con Claude Desktop. Generalmente no necesitas activar el .venv manualmente para este método, ya que fastmcp install se encarga de la creación del entorno.

Instala el servidor para Claude:
```
# From the python-notebook-mcp directory
fastmcp install server.py --name "Jupyter Notebook MCP"
```
- fastmcp install usa uv internamente para crear el entorno e instalar las dependencias desde requirements.txt.
- El servidor ahora aparecerá en la configuración de desarrollador de Claude Desktop y se puede habilitar allí. Generalmente no necesitas editar manualmente claude_desktop_config.json cuando usas fastmcp install.

📘 Uso

Concepto clave: Inicialización del espacio de trabajo

Independientemente de cómo ejecutes el servidor, la primera acción que debes realizar desde tu asistente de IA es inicializar el espacio de trabajo. Esto le indica al servidor dónde se encuentran tus archivos de proyecto y notebooks.

# Example tool call from the client (syntax may vary)
initialize_workspace(directory="/full/absolute/path/to/your/project_folder")

⚠️ Debes proporcionar la ruta absoluta completa al directorio que contiene tus notebooks. No se aceptan rutas relativas ni rutas como .. El servidor confirmará la ruta y listará cualquier notebook existente que encuentre.

Operaciones principales

Una vez que el espacio de trabajo esté inicializado, puedes usar las herramientas disponibles:

# List notebooks
list_notebooks()

# Create a new notebook
create_notebook(filepath="analysis/new_analysis.ipynb", title="My New Analysis")

# Add a code cell to the notebook
add_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")

# Read the first cell (index 0)
read_cell(filepath="analysis/new_analysis.ipynb", cell_index=0)

# Edit the second cell (index 1)
edit_cell(filepath="analysis/new_analysis.ipynb", cell_index=1, content="# This is updated markdown")

# Read the output of the second cell (index 1) after execution (if any)
read_cell_output(filepath="analysis/new_analysis.ipynb", cell_index=1)

# Read the entire notebook structure
read_notebook(filepath="analysis/new_analysis.ipynb")

🛠️ Herramientas disponibles

Herramienta	Descripción
`initialize_workspace`	PRIMER PASO OBLIGATORIO. Establece la ruta absoluta del espacio de trabajo.
`list_notebooks`	Lista todos los archivos `.ipynb` encontrados en el directorio del espacio de trabajo.
`create_notebook`	Crea un nuevo notebook de Jupyter vacío si no existe.
`read_notebook`	Lee la estructura y el contenido completo de un notebook.
`read_cell`	Lee el contenido y los metadatos de una celda específica por índice.
`edit_cell`	Modifica el contenido fuente de una celda existente por índice.
`add_cell`	Agrega una nueva celda de código o markdown en un índice específico o al final.
`read_notebook_outputs`	Lee todas las salidas de todas las celdas de código en un notebook.
`read_cell_output`	Lee la(s) salida(s) de una celda de código específica por índice.

🧪 Desarrollo y depuración

Si necesitas depurar el servidor en sí:

Ejecución directa: Usa uv run python server.py y observa la salida del terminal para errores o declaraciones de impresión.

Modo de desarrollo FastMCP: Para pruebas interactivas con el MCP Inspector:

# Make sure fastmcp is installed in your environment
# uv pip install fastmcp
uv run fastmcp dev server.py

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulta el archivo LICENSE para más detalles.

Python Notebook MCP

Documentación