Jupythunder

🚀 Jupythunder Project

Jupythunder is a project that enables communication between Jupyter kernels and MCP clients, providing API interfaces for interactive computing and data visualization.

🚀 Quick Start

Start the MCP Server

conda activate jupythunder
cd jupythunder
python jupythunder_server.py --port 8000

Test Jupyter Connection

conda activate jupythunder
cd jupythunder
python jupythunder_client.py --connect http://localhost:8000

✨ Features

MCP Server Functions

1. Handle communication between Jupyter kernels and MCP clients.
2. Provide API interfaces for interactive computing and data visualization.

Jupyter Connection Steps

1. Start the Jupyter server and obtain the token.
2. Configure the connection parameters in jupythunder_client.py.
3. Run the client to establish a connection.

📦 Installation

MCP Server Configuration

conda create -n jupythunder python>=3.7
conda activate jupythunder
pip install mcp[cli] requests websocket-client python-dotenv urllib3
git clone https://github.com/yourusername/jupythunder.git
cd jupythunder
python jupythunder_server.py --port 8000

Jupyter Connection Configuration

conda create -n jupythunder python>=3.7
conda activate jupythunder
pip install requests websocket-client python-dotenv urllib3
git clone https://github.com/yourusername/jupythunder.git
cd jupythunder
python jupythunder_client.py --connect http://localhost:8000

📚 Documentation

Project Structure

jupythunder/
├── jupythunder_server.py          # MCP server implementation
├── jupythunder_client.py          # Jupyter API client
├── tools.py                       # MCP tool implementation
├── utils.py                       # Utility functions
└── requirements.txt               # Project dependencies

Detailed Configuration

Environment Variable Settings

export JUPYTHUNDER_PORT=8000
export JUPYTHUNDER_LOG_LEVEL=DEBUG

Configuration File Example

# jupythunder_config.py
JUPYTHUNDER_HOST = "localhost"
JUPYTHUNDER_PORT = 8000
LOG_LEVEL = "INFO"

Common Issues

Unable to Connect to the MCP Server jupythunder: spawn python ENOENT

This error indicates that the Python executable file cannot be found. Please check the following configurations:

1. Specify Python using an absolute path:

   {
     "mcpServers": {
       "jupythunder": {
         "command": "/absolute/path/python",
         "args": ["/absolute/path/jupythunder_server.py"]
       }
     }
   }
   

   Confirm the Python installation location:

   which python  # macOS/Linux
   where python  # Windows
   

2. Use the python3 command:

   {
     "mcpServers": {
       "jupythunder": {
         "command": "python3",
         "args": ["/absolute/path/jupythunder_server.py"]
       }
     }
   }
   

Troubleshooting

Jupyter Connection Failure

• Confirm that the Jupyter server is running.
• Check if the provided URL and token are correct.
• Check the firewall settings.

Failure to Create or Open a Notebook

• Confirm that you have write permissions on the Jupyter server.
• Check that the notebook name does not contain special characters.
• Confirm that there is no notebook with the same name already existing.

Project Components

1. FastMCP Server: Implement efficient computing task processing.
2. Jupyter Client: Provide a user interaction interface and API calls.
3. Toolkit: Include functions such as data processing and logging.

Dependency Management

Installation Requirements

• Python >=3.7
• conda environment manager

Third - Party Libraries

• mcp[cli]
• requests
• websocket-client
• python-dotenv
• urllib3

Logging System

conda activate jupythunder
cd jupythunder
python logging_server.py --port 8001

Extension Modules

Custom Kernel Support

conda install -n jupythunder custom-kernel

Additional Feature Packages

pip install extra_features

Appendix

Command - Line Parameters

• --port: Specify the server port, default is 8000.
• --log-level: Set the log level, options are DEBUG/INFO/ERROR.

Error Codes

Supplementary Notes

• All code examples are in Python syntax.
• Configuration files should be placed in the project root directory.