Python Notebook MCP

Permite que assistentes de IA interajam com notebooks Jupyter locais (.ipynb).

Documentação

Python Notebook MCP

Servidor MCP que permite que assistentes de IA interajam com notebooks Jupyter através do Protocolo de Contexto de Modelo.

Este servidor permite que assistentes de IA compatíveis (como Cursor ou Claude Desktop) interajam com arquivos de Notebook Jupyter (.ipynb) na sua máquina local.

📋 Pré-requisitos

Antes de começar, certifique-se de ter o seguinte instalado:

Python: Versão 3.10 ou superior.

uv: O instalador rápido de pacotes Python e gerenciador de ambientes virtuais da Astral. Se você não o tiver, instale-o:

# 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 do Claude Desktop): Se você planeja usar o método fastmcp install para o Claude Desktop, você precisa do comando fastmcp disponível.
```
# Using uv
uv pip install fastmcp

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

🔧 Configuração

Clone o Repositório:

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

Escolha o Método de Configuração:
- Opção A: Configuração Automatizada (Recomendada) Execute o script apropriado para o seu sistema operacional a partir do diretório raiz do projeto (onde você acabou de 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
```
  Esses scripts criarão o .venv, instalarão as dependências e exibirão os caminhos exatos necessários para a configuração do seu cliente MCP.
- Opção B: Configuração Manual Siga estes passos se preferir controle manual ou encontrar problemas com os scripts.
  1. Crie e Ative o Ambiente 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
```
    (Você deve ver (.venv) ou algo semelhante no início do prompt do seu shell)
  2. Instale as Dependências:
```
# Make sure your venv is active
uv pip install -r requirements.txt
```

▶️ Executando o Servidor

Certifique-se de que seu ambiente virtual (.venv) esteja ativado se você usou a configuração manual.

Método 1: Execução Direta (Recomendado para Cursor, Uso Geral)

Este método usa uv run para executar o script do servidor diretamente usando seu ambiente Python atual (que agora deve ter as dependências instaladas).

Execute o Servidor:
```
# From the python-notebook-mcp directory
uv run python server.py
```
O servidor iniciará e exibirá mensagens de status, incluindo o diretório de trabalho (não inicializado).
Configuração do Cliente (mcp.json): Configure seu cliente MCP (por exemplo, Cursor) para conectar. Crie ou edite o arquivo de configuração MCP do cliente (por exemplo, .cursor/mcp.json no seu espaço de trabalho).

Modelo (Recomendado):
```
{
  "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 que o caminho completo para o Python? Aplicativos GUI como o Cursor podem não herdar o mesmo ambiente PATH que o seu terminal. Especificar o caminho exato para o interpretador Python dentro do seu .venv garante que o servidor execute com o ambiente e as dependências corretos. ⚠️ IMPORTANTE: Substitua os caminhos de exemplo pelos caminhos absolutos reais no seu sistema.

Método 2: Integração com Claude Desktop (`fastmcp install`)

Este método usa a ferramenta fastmcp para criar um ambiente dedicado e isolado para o servidor e registrá-lo no Claude Desktop. Geralmente você não precisa ativar o .venv manualmente para este método, pois o fastmcp install cuida da criação do ambiente.

Instale o Servidor para Claude:
```
# From the python-notebook-mcp directory
fastmcp install server.py --name "Jupyter Notebook MCP"
```
- O fastmcp install usa uv nos bastidores para criar o ambiente e instalar as dependências do requirements.txt.
- O servidor agora aparecerá nas configurações de desenvolvedor do Claude Desktop e poderá ser habilitado lá. Geralmente você não precisa editar manualmente o claude_desktop_config.json ao usar o fastmcp install.

📘 Uso

Conceito-chave: Inicialização do Espaço de Trabalho

Independentemente de como você execute o servidor, a primeira ação que você deve tomar no seu assistente de IA é inicializar o espaço de trabalho. Isso informa ao servidor onde seus arquivos de projeto e notebooks estão localizados.

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

⚠️ Você deve fornecer o caminho absoluto completo para o diretório que contém seus notebooks. Caminhos relativos ou caminhos como . não são aceitos. O servidor confirmará o caminho e listará quaisquer notebooks existentes encontrados.

Operações Principais

Uma vez que o espaço de trabalho esteja inicializado, você pode usar as ferramentas disponíveis:

# 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")

🛠️ Ferramentas Disponíveis

Ferramenta	Descrição
`initialize_workspace`	PRIMEIRO PASSO OBRIGATÓRIO. Define o caminho absoluto para o espaço de trabalho.
`list_notebooks`	Lista todos os arquivos `.ipynb` encontrados no diretório do espaço de trabalho.
`create_notebook`	Cria um novo notebook Jupyter vazio se ele não existir.
`read_notebook`	Lê a estrutura e o conteúdo completo de um notebook.
`read_cell`	Lê o conteúdo e os metadados de uma célula específica por índice.
`edit_cell`	Modifica o conteúdo de origem de uma célula existente por índice.
`add_cell`	Adiciona uma nova célula de código ou markdown em um índice específico ou no final.
`read_notebook_outputs`	Lê todas as saídas de todas as células de código em um notebook.
`read_cell_output`	Lê a(s) saída(s) de uma célula de código específica por índice.

🧪 Desenvolvimento e Depuração

Se você precisar depurar o próprio servidor:

Execute Diretamente: Use uv run python server.py e observe a saída do terminal para erros ou declarações de impressão.

Modo de Desenvolvimento FastMCP: Para testes interativos com o MCP Inspector:

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

📄 Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Python Notebook MCP

Documentação