Python notebook mcp

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

📋 Requisitos previos

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

1. Python: versión 3.10 o superior.
2. uv : El rápido instalador de paquetes de Python y administrador de entornos virtuales de Astral. Si no lo tiene, instálelo:
   # 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)
3. CLI fastmcp (opcional, para fastmcp install de Claude Desktop): si planea utilizar el método fastmcp install para Claude Desktop, necesita tener el comando fastmcp disponible.
   # Using uv uv pip install fastmcp # Or using pipx (recommended for CLI tools) pipx install fastmcp

🔧 Configuración

1. Clonar el repositorio:
   git clone https://github.com/UsamaK98/python-notebook-mcp.git # Or your fork/local path cd python-notebook-mcp
2. Elija el método de configuración:
   • Opción A: Configuración automatizada (recomendada) Ejecute el script apropiado para su sistema operativo desde el directorio raíz del proyecto (donde acaba de ingresar cd -ed).
     • macOS / Linux:
       # Make script executable (if needed) chmod +x ./install_unix.sh # Run the script bash ./install_unix.sh
     • Ventanas (PowerShell):GXP5 Estos scripts crearán el .venv , instalarán dependencias y generarán las rutas exactas necesarias para la configuración de su cliente MCP.
   • Opción B: Configuración manual Siga estos pasos si prefiere el control manual o tiene problemas con los scripts.
     1. Crear y activar 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ía ver (.venv) o algo similar al comienzo del indicador de shell)
     2. Dependencias de instalación:
        # Make sure your venv is active uv pip install -r requirements.txt

▶️ Ejecución del servidor

Asegúrese de que su entorno virtual ( .venv ) esté activado si utilizó la configuración manual.

Método 1: Ejecución directa (recomendado para cursores de uso general)

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

1. Ejecutar el servidor:
   # From the python-notebook-mcp directory uv run python server.py
   El servidor se iniciará e imprimirá mensajes de estado, incluido el directorio del espacio de trabajo (no inicializado).
2. Configuración del cliente ( mcp.json ): Configure su cliente MCP (p. ej., Cursor) para conectarse. Cree o edite el archivo de configuración MCP del cliente (p. ej., .cursor/mcp.json en su 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? Es posible que las aplicaciones GUI como Cursor no hereden 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 correctas. ⚠️ IMPORTANTE: Reemplaza las rutas de marcador de posición con las rutas absolutas reales de tu sistema.

Método 2: Integración de escritorio de Claude ( fastmcp install )

Este método utiliza la herramienta fastmcp para crear un entorno aislado y dedicado para el servidor y registrarlo en Claude Desktop. Generalmente, no es necesario activar manualmente el .venv , ya que fastmcp install gestiona la creación del entorno.

1. Instalar el servidor para Claude:
   # From the python-notebook-mcp directory fastmcp install server.py --name "Jupyter Notebook MCP"
   • fastmcp install utiliza uv detrás de escena para crear el entorno e instalar dependencias desde requirements.txt .
   • El servidor aparecerá ahora en la configuración de desarrollador de Claude Desktop y podrá habilitarse desde allí. Generalmente, no es necesario editar manualmente claude_desktop_config.json al usar fastmcp install .

📘 Uso

Concepto clave: Inicialización del espacio de trabajo

Independientemente de cómo ejecute el servidor, la primera acción que debe realizar su asistente de IA es inicializar el espacio de trabajo. Esto le indica al servidor dónde se encuentran los archivos de su proyecto y los cuadernos.

⚠️ Debe proporcionar la ruta absoluta completa al directorio que contiene sus notebooks. No se aceptan rutas relativas ni rutas como . El servidor confirmará la ruta y listará los notebooks que encuentre.

Operaciones principales

Una vez inicializado el espacio de trabajo, puedes utilizar las herramientas disponibles:

🛠️ Herramientas disponibles

🧪 Desarrollo y depuración

Si necesita depurar el servidor en sí:

• Ejecutar directamente: use uv run python server.py y observe la salida del terminal en busca de errores o declaraciones de impresión.
• Modo de desarrollo FastMCP: para pruebas interactivas con el inspector MCP:
  # 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: consulte el archivo de LICENCIA para obtener más detalles.