Content
# timeverse-command-mcp
> A [MCP (Model Context Protocol)](https://modelcontextprotocol.io) Server for executing shell / Python / Node commands across platforms.
[](https://pypi.org/project/timeverse-command-mcp/)
[](https://pypi.org/project/timeverse-command-mcp/)
[](LICENSE)
---
## What can it do?
It allows any MCP-enabled AI client (Timeverse Studio, Claude Desktop, Cursor, Continue, etc.) to **directly operate your local machine** with three tools:
| Tool | Function | Applicable Platforms |
|------|----------|----------------------|
| `bash` | Execute shell commands | macOS / Linux / Windows |
| `python` | Execute Python code snippets | All platforms |
| `node` | Execute JavaScript code snippets | All platforms |
Typical usage (let Claude do it for you):
```
"Use bash to list the 5 largest files in /tmp"
"Use python to calculate 1+2+...+100"
"Use node to parse this JSON and tell me user.name"
```
---
## Installation
### Method 1: pip (recommended)
```bash
pip install timeverse-command-mcp
```
After installation, you will get a `timeverse-command-mcp` command.
### Method 2: Source installation (for development)
```bash
git clone https://github.com/elimyliu/timeverse-command-mcp.git
cd timeverse-command-mcp
pip install -e ".[dev]"
```
---
## Integration with Claude Desktop
Edit the Claude Desktop configuration file (location see below):
| Operating System | Configuration Path |
|---------|-------------------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
Add the following content:
```json
{
"mcpServers": {
"timeverse-command": {
"command": "timeverse-command-mcp",
"args": [],
"env": {}
}
}
}
```
Restart Claude Desktop, and you will see `bash` / `python` / `node` three tools in the tool list.
> For detailed configuration instructions, Cursor / Continue / Cline and other client access methods, please refer to [docs/USAGE.md](docs/USAGE.md).
## Python API
In addition to serving as an MCP Server, this package can also be used as a Python library:
```python
import asyncio
from timeverse_command import AsyncCommandSession
async def main():
session = AsyncCommandSession(
tool_calls_id="demo-1",
command="echo hello && echo world",
tool_name="bash",
)
async for chunk in session.run():
if chunk["stream"] == "stdout":
print(f"[out] {chunk['delta']}")
elif chunk["stream"] == "exit":
print(f"[exit] code={chunk['exit_code']} status={chunk['status']}")
asyncio.run(main())
```
Output:
```
[out] hello
[out] world
[exit] code=0 status=success
```
More APIs (cancel, global executor, etc.) see [docs/USAGE.md](docs/USAGE.md).
---
## Development
```bash
# Clone
git clone https://github.com/elimyliu/timeverse-command-mcp.git
cd timeverse-command-mcp
# Install dependencies (including dev tools)
pip install -e ".[dev]"
# Run tests
pytest
# Code style
ruff check src/
ruff format src/
# Type checking
mypy src/
```
---
## Protocol
- **MCP transmission**: stdio (standard)
- **No dependence** on any private extensions, can be used with all MCP stdio-enabled clients
- Enhanced capabilities (streaming / cancellation / danger confirmation) provided exclusively by TimeVerse Studio client, other clients run with "basic capabilities"
---
## License
MIT © TimeVerse Studio
