| Name | jupyter-kernel-mcp JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | MCP server for stateful Jupyter kernel development with multi-kernel support |
| upload_time | 2025-07-23 06:36:13 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
ai
assistant
jupyter
kernel
mcp
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Jupyter Kernel MCP
[](https://pypi.org/project/jupyter-kernel-mcp/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
A Model Context Protocol (MCP) server that provides stateful Jupyter kernel development with multi-kernel support for AI agents and assistants.
## Table of contents
1. [Project description](#project-description)
2. [Who this project is for](#who-this-project-is-for)
3. [Project dependencies](#project-dependencies)
4. [Instructions for using Jupyter Kernel MCP](#instructions-for-using-jupyter-kernel-mcp)
5. [Troubleshooting](#troubleshooting)
6. [Contributing guidelines](#contributing-guidelines)
7. [Additional documentation](#additional-documentation)
8. [How to get help](#how-get-help)
9. [Terms of use](#terms-of-use)
## Project description
With _Jupyter Kernel MCP_ you can execute Python code in persistent, isolated environments that maintain state between executions—perfect for AI agents performing complex data analysis workflows.
_Jupyter Kernel MCP_ helps you build stateful AI agent workflows that can load datasets, perform transformations, and analyze results across multiple interactions without losing variables or computed state.
Unlike traditional stateless code execution, _Jupyter Kernel MCP_ preserves variables, imports, and computed results between AI agent messages, enabling sophisticated multi-step data science workflows.
### Key Features
- **🔄 Persistent State**: Variables and imports persist between code executions
- **🚀 Multi-Kernel Support**: Create and manage multiple isolated kernel environments
- **🤖 AI-Agent Ready**: Seamless integration with Claude Code and other MCP clients
- **📊 Data Science Workflows**: Perfect for iterative data analysis and exploration
- **⚡ Fast Communication**: Direct socket-based communication with Jupyter kernels
- **🛠 Easy Management**: Simple kernel lifecycle management (start, stop, reset, list)
## Who this project is for
This project is intended for AI developers, data scientists, and automation engineers who want to build intelligent agents that can perform stateful data analysis and complex computational workflows.
Perfect for:
- Building AI agents that analyze datasets across multiple interactions
- Creating persistent computational environments for LLMs
- Developing stateful data science workflows with AI assistants
- Prototyping and exploring APIs with maintained context
## Project dependencies
Before using Jupyter Kernel MCP, ensure you have:
* **Python 3.10 or higher** - Required for MCP SDK compatibility
* **Claude Code, Cline, or another MCP client** - To interact with the server
* **Jupyter dependencies** - Automatically installed with the package
## Instructions for using Jupyter Kernel MCP
Get started with Jupyter Kernel MCP by installing the package and adding it to your MCP client.
### Install Jupyter Kernel MCP
#### From PyPI (Recommended)
**Install using pip:**
```bash
pip install jupyter-kernel-mcp
```
Or using uv:
```bash
uv add jupyter-kernel-mcp
```
#### From GitHub (Development Version)
To install the latest development version directly from GitHub:
```bash
uv tool install git+https://github.com/codewithcheese/jupyter-kernel-mcp.git
```
#### Verify Installation
```bash
jupyter-kernel-mcp --help
```
### Configure with Claude Code
1. **Add the server to Claude Code:**
```bash
claude mcp add jupyter-kernel jupyter-kernel-mcp
```
2. **Verify the server is listed:**
```bash
claude mcp list
```
### Configure with other MCP clients
1. **Add to your MCP client configuration** (example for `mcp_config.json`):
```json
{
"servers": {
"jupyter-kernel": {
"command": "jupyter-kernel-mcp"
}
}
}
```
### Run Jupyter Kernel MCP
1. **The server starts automatically when called by your MCP client**
No manual startup required - the server launches when your MCP client connects.
2. **Start your first kernel:**
In Claude Code or your MCP client:
```
Please start a new Jupyter kernel for data analysis
```
3. **Execute stateful code:**
```
Load this dataset and show me the first few rows:
import pandas as pd
df = pd.read_csv('data.csv')
df.head()
```
4. **Continue the analysis in follow-up messages:**
```
Now group the data by category and calculate the mean values
```
The `df` variable persists from the previous execution!
### Available Tools
| Tool | Description |
|------|-------------|
| `start_kernel` | Create a new Jupyter kernel (with optional custom ID) |
| `execute_python` | Execute Python code in a specific kernel |
| `list_kernels` | Show all active kernels |
| `list_variables` | Display variables in a kernel's namespace |
| `get_kernel_status` | Get detailed kernel information |
| `stop_kernel` | Stop and remove a specific kernel |
| `reset_kernel` | Reset a kernel (clears all variables) |
### Troubleshooting
<table>
<tr>
<td><strong>Issue</strong></td>
<td><strong>Solution</strong></td>
</tr>
<tr>
<td>Server won't start - "No module named 'jupyter_client'"</td>
<td>Install dependencies: <code>pip install jupyter-client</code></td>
</tr>
<tr>
<td>Kernel creation fails</td>
<td>Ensure Python 3.10+ is installed and accessible</td>
</tr>
<tr>
<td>MCP client can't find server</td>
<td>Verify installation: <code>which jupyter-kernel-mcp</code></td>
</tr>
<tr>
<td>Variables not persisting between executions</td>
<td>Ensure you're using the same kernel_id for related executions</td>
</tr>
</table>
**Other troubleshooting resources:**
* Check server logs for detailed error messages
* Verify your MCP client supports the required MCP protocol version
* Ensure no firewall is blocking local kernel connections
## Contributing guidelines
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
- How to submit bug reports and feature requests
- Development setup and testing procedures
- Code style guidelines and review process
## Additional documentation
For more information:
* [Model Context Protocol Specification](https://modelcontextprotocol.io/) - Official MCP documentation
* [Jupyter Client Documentation](https://jupyter-client.readthedocs.io/) - Jupyter kernel communication protocol
* [Claude Code MCP Guide](https://docs.anthropic.com/en/docs/claude-code/mcp) - Using MCP servers with Claude
## How to get help
Need assistance? Here's how to get support:
* **GitHub Issues** - [Report bugs or request features](https://github.com/codewithcheese/jupyter-kernel-mcp/issues)
* **Email** - Contact the maintainer at [tom@codewithcheese.com](mailto:tom@codewithcheese.com)
* **MCP Community** - Join discussions in MCP community forums
## Terms of use
Jupyter Kernel MCP is licensed under the [MIT License](LICENSE).
---
*Built with ❤️ for the AI agent development community*
Raw data
{
"_id": null,
"home_page": null,
"name": "jupyter-kernel-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, assistant, jupyter, kernel, mcp",
"author": null,
"author_email": "Tom M <tom@codewithcheese.com>",
"download_url": "https://files.pythonhosted.org/packages/4d/5c/ac320ae6b30f71a8113c61abedaa505788a4092563291720922151f7632c/jupyter_kernel_mcp-0.1.1.tar.gz",
"platform": null,
"description": "# Jupyter Kernel MCP\n\n[](https://pypi.org/project/jupyter-kernel-mcp/)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\nA Model Context Protocol (MCP) server that provides stateful Jupyter kernel development with multi-kernel support for AI agents and assistants.\n\n## Table of contents\n\n1. [Project description](#project-description)\n2. [Who this project is for](#who-this-project-is-for)\n3. [Project dependencies](#project-dependencies)\n4. [Instructions for using Jupyter Kernel MCP](#instructions-for-using-jupyter-kernel-mcp)\n5. [Troubleshooting](#troubleshooting)\n6. [Contributing guidelines](#contributing-guidelines)\n7. [Additional documentation](#additional-documentation)\n8. [How to get help](#how-get-help)\n9. [Terms of use](#terms-of-use)\n\n## Project description\n\nWith _Jupyter Kernel MCP_ you can execute Python code in persistent, isolated environments that maintain state between executions\u2014perfect for AI agents performing complex data analysis workflows.\n\n_Jupyter Kernel MCP_ helps you build stateful AI agent workflows that can load datasets, perform transformations, and analyze results across multiple interactions without losing variables or computed state.\n\nUnlike traditional stateless code execution, _Jupyter Kernel MCP_ preserves variables, imports, and computed results between AI agent messages, enabling sophisticated multi-step data science workflows.\n\n### Key Features\n\n- **\ud83d\udd04 Persistent State**: Variables and imports persist between code executions\n- **\ud83d\ude80 Multi-Kernel Support**: Create and manage multiple isolated kernel environments \n- **\ud83e\udd16 AI-Agent Ready**: Seamless integration with Claude Code and other MCP clients\n- **\ud83d\udcca Data Science Workflows**: Perfect for iterative data analysis and exploration\n- **\u26a1 Fast Communication**: Direct socket-based communication with Jupyter kernels\n- **\ud83d\udee0 Easy Management**: Simple kernel lifecycle management (start, stop, reset, list)\n\n## Who this project is for\n\nThis project is intended for AI developers, data scientists, and automation engineers who want to build intelligent agents that can perform stateful data analysis and complex computational workflows.\n\nPerfect for:\n- Building AI agents that analyze datasets across multiple interactions\n- Creating persistent computational environments for LLMs\n- Developing stateful data science workflows with AI assistants\n- Prototyping and exploring APIs with maintained context\n\n## Project dependencies\n\nBefore using Jupyter Kernel MCP, ensure you have:\n\n* **Python 3.10 or higher** - Required for MCP SDK compatibility\n* **Claude Code, Cline, or another MCP client** - To interact with the server\n* **Jupyter dependencies** - Automatically installed with the package\n\n## Instructions for using Jupyter Kernel MCP\n\nGet started with Jupyter Kernel MCP by installing the package and adding it to your MCP client.\n\n### Install Jupyter Kernel MCP\n\n#### From PyPI (Recommended)\n\n**Install using pip:**\n\n```bash\npip install jupyter-kernel-mcp\n```\n\nOr using uv:\n\n```bash\nuv add jupyter-kernel-mcp\n```\n\n#### From GitHub (Development Version)\n\nTo install the latest development version directly from GitHub:\n\n```bash\nuv tool install git+https://github.com/codewithcheese/jupyter-kernel-mcp.git\n```\n\n#### Verify Installation\n\n```bash\njupyter-kernel-mcp --help\n```\n\n### Configure with Claude Code\n\n1. **Add the server to Claude Code:**\n\n ```bash\n claude mcp add jupyter-kernel jupyter-kernel-mcp\n ```\n\n2. **Verify the server is listed:**\n\n ```bash\n claude mcp list\n ```\n\n### Configure with other MCP clients\n\n1. **Add to your MCP client configuration** (example for `mcp_config.json`):\n\n ```json\n {\n \"servers\": {\n \"jupyter-kernel\": {\n \"command\": \"jupyter-kernel-mcp\"\n }\n }\n }\n ```\n\n### Run Jupyter Kernel MCP\n\n1. **The server starts automatically when called by your MCP client**\n\n No manual startup required - the server launches when your MCP client connects.\n\n2. **Start your first kernel:**\n\n In Claude Code or your MCP client:\n ```\n Please start a new Jupyter kernel for data analysis\n ```\n\n3. **Execute stateful code:**\n\n ```\n Load this dataset and show me the first few rows:\n \n import pandas as pd\n df = pd.read_csv('data.csv')\n df.head()\n ```\n\n4. **Continue the analysis in follow-up messages:**\n\n ```\n Now group the data by category and calculate the mean values\n ```\n\n The `df` variable persists from the previous execution!\n\n### Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `start_kernel` | Create a new Jupyter kernel (with optional custom ID) |\n| `execute_python` | Execute Python code in a specific kernel |\n| `list_kernels` | Show all active kernels |\n| `list_variables` | Display variables in a kernel's namespace |\n| `get_kernel_status` | Get detailed kernel information |\n| `stop_kernel` | Stop and remove a specific kernel |\n| `reset_kernel` | Reset a kernel (clears all variables) |\n\n### Troubleshooting\n\n<table>\n <tr>\n <td><strong>Issue</strong></td>\n <td><strong>Solution</strong></td>\n </tr>\n <tr>\n <td>Server won't start - \"No module named 'jupyter_client'\"</td>\n <td>Install dependencies: <code>pip install jupyter-client</code></td>\n </tr>\n <tr>\n <td>Kernel creation fails</td>\n <td>Ensure Python 3.10+ is installed and accessible</td>\n </tr>\n <tr>\n <td>MCP client can't find server</td>\n <td>Verify installation: <code>which jupyter-kernel-mcp</code></td>\n </tr>\n <tr>\n <td>Variables not persisting between executions</td>\n <td>Ensure you're using the same kernel_id for related executions</td>\n </tr>\n</table>\n\n**Other troubleshooting resources:**\n* Check server logs for detailed error messages\n* Verify your MCP client supports the required MCP protocol version\n* Ensure no firewall is blocking local kernel connections\n\n## Contributing guidelines\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:\n\n- How to submit bug reports and feature requests\n- Development setup and testing procedures \n- Code style guidelines and review process\n\n## Additional documentation\n\nFor more information:\n\n* [Model Context Protocol Specification](https://modelcontextprotocol.io/) - Official MCP documentation\n* [Jupyter Client Documentation](https://jupyter-client.readthedocs.io/) - Jupyter kernel communication protocol\n* [Claude Code MCP Guide](https://docs.anthropic.com/en/docs/claude-code/mcp) - Using MCP servers with Claude\n\n## How to get help\n\nNeed assistance? Here's how to get support:\n\n* **GitHub Issues** - [Report bugs or request features](https://github.com/codewithcheese/jupyter-kernel-mcp/issues)\n* **Email** - Contact the maintainer at [tom@codewithcheese.com](mailto:tom@codewithcheese.com)\n* **MCP Community** - Join discussions in MCP community forums\n\n## Terms of use\n\nJupyter Kernel MCP is licensed under the [MIT License](LICENSE).\n\n---\n\n*Built with \u2764\ufe0f for the AI agent development community*",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for stateful Jupyter kernel development with multi-kernel support",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/codewithcheese/jupyter-kernel-mcp",
"Issues": "https://github.com/codewithcheese/jupyter-kernel-mcp/issues",
"Repository": "https://github.com/codewithcheese/jupyter-kernel-mcp.git"
},
"split_keywords": [
"ai",
" assistant",
" jupyter",
" kernel",
" mcp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ac732197b5dc6bebac60e502321a8fea3e1ff217420297af0cfacd41bb60744f",
"md5": "ddfac7569125278400ef57bdef430168",
"sha256": "19c0e5dce2ec02ec1c1785d45e6aa1f0c6f0a3668864e1eeef43542df3152202"
},
"downloads": -1,
"filename": "jupyter_kernel_mcp-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ddfac7569125278400ef57bdef430168",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 8324,
"upload_time": "2025-07-23T06:36:11",
"upload_time_iso_8601": "2025-07-23T06:36:11.888464Z",
"url": "https://files.pythonhosted.org/packages/ac/73/2197b5dc6bebac60e502321a8fea3e1ff217420297af0cfacd41bb60744f/jupyter_kernel_mcp-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4d5cac320ae6b30f71a8113c61abedaa505788a4092563291720922151f7632c",
"md5": "046145b028b4f8ce138cd66352886410",
"sha256": "195c2cdebb6f8c6ac336c7a196135e62fcda4a8ba2e420151826e568a529dbcb"
},
"downloads": -1,
"filename": "jupyter_kernel_mcp-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "046145b028b4f8ce138cd66352886410",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 63800,
"upload_time": "2025-07-23T06:36:13",
"upload_time_iso_8601": "2025-07-23T06:36:13.430221Z",
"url": "https://files.pythonhosted.org/packages/4d/5c/ac320ae6b30f71a8113c61abedaa505788a4092563291720922151f7632c/jupyter_kernel_mcp-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 06:36:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "codewithcheese",
"github_project": "jupyter-kernel-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "jupyter-kernel-mcp"
}
