Cursor Notebook MCP

🚀 cursor-notebook-mcp

This project named cursor-notebook-mcp aims to provide Cursor with support for Jupyter notebook files (.ipynb). It allows users to read, write, and modify notebook files through Cursor.

🚀 Quick Start

This project provides support for Jupyter notebook files (.ipynb) in Cursor, enabling users to perform read, write, and modification operations on notebook files.

📦 Installation

Install using a virtual environment

It is recommended to use a virtual environment to install the project:

python -m venv .venv
source .venv/bin/activate  # Use the activate script on Windows
pip install .

Global installation (not recommended)

If you choose global installation, make sure you have administrator privileges activated:

sudo pip install .

📚 Documentation

The project provides the following configuration options:

• Log file storage path: Defaults to ~/.cursor_notebook_mcp, can be set via the command-line parameter --log-level.
• Log level: Supports DEBUG, INFO, WARNING, ERROR, and CRITICAL, defaults to INFO.
• Maximum cell source data size: Defaults to 10 MiB, can be adjusted via --max-cell-source-size.
• Maximum cell output data size: Defaults to 10 MiB, can be adjusted via --max-cell-output-size.

🔧 Technical Details

Security Precautions

• Workspace root directory enforcement: The server must specify the allowed root directory via --allow-root when starting; otherwise, it will not run properly.
• Path handling: The server uses os.path.realpath to resolve paths and checks if they are within the allowed range before operations.
• Input validation: Basic check for the .ipynb file extension.

Known Limitations

• Inability to execute cells: This server does not support cell execution functionality and is limited to operations on the .ipynb file structure.

Development and Testing

1. Create a virtual environment and install development dependencies:

   python -m venv .venv
   source .venv/bin/activate
   pip install -e ".[dev]"
   

2. Execute tests:

   ./run_tests.sh 
   # Or run specific tests
   # ./run_tests.sh tests/test_notebook_tools.py
   

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a new branch: git checkout -b feature/amazing-feature
3. Make modifications.
4. Run tests to ensure no existing functionality is broken.
5. Commit changes: git commit -m 'Add amazing feature'
6. Push to the branch and submit a pull request.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

👨‍💻 Author

This project is created and maintained by Jim Beno. Contact email: jim@jimbeno.net