Skip to content

MCP Interactive Manager Documentation

Overview

mcp_interactive.py is an interactive menu-driven Python script that provides comprehensive management and interaction capabilities for the Ollama MCP (Model Context Protocol) Server. It offers a user-friendly terminal interface for server lifecycle management, command execution, environment configuration, and monitoring.

Table of Contents

Features

Core Capabilities

  • Server Lifecycle Management: Start, stop, and monitor MCP server processes
  • Process Validation: Intelligent PID file management with process verification using psutil
  • Environment Management: Persistent environment variable configuration
  • Interactive Command Execution: Execute MCP commands with guided parameter input
  • Real-time Monitoring: Server status, Ollama connection, and available models display
  • Comprehensive Logging: Separate log files for standard output and errors
  • Cross-Platform Support: Windows and Unix/Linux compatibility
  • Automatic Cleanup: Stale pipe file and PID file management

Platform-Specific Features

  • Windows: Uses psutil.Process.terminate() instead of SIGKILL for graceful shutdown
  • Unix/Linux: Standard signal-based process management
  • Cross-platform: Automatic detection and appropriate handling

Prerequisites

Software

Tool Minimum Version Why it's needed
Python 3.10 or newer Project code targets Python 3.10+.
Poetry >=1.6 Handles the project's virtual environment and dependencies.
Ollama Latest stable Required for the mcp_ollama_python integration.

Tip: If you don't have Poetry installed, run 

curl -sSL https://install.python-poetry.org | python3 -
or use your system package manager (e.g. brew install poetry on macOS, or pip install poetry on Windows).

Python Packages

The project's dependencies are declared in pyproject.toml:

  • httpx >=0.27.0
  • pydantic >=2.7.0
  • rich >=13.7.0
  • mcp >=1.0.0
  • psutil >=7.1.3

No requirements.txt is needed – Poetry takes care of resolving and pinning the exact versions.

Installation

# 1. Clone the repository (if you haven't already)
git clone https://github.com/your-repo/mcp-ollama-python.git
cd mcp-ollama-python

# 2. (Optional) Verify that you are on the right Python version
python --version   # Should print 3.10.x or newer

# 3. Install the project's dependencies and create a virtual environment
poetry install

# 4. (Optional) Activate the virtual environment manually
poetry shell
#   • You'll now be inside the Poetry-managed venv and can run commands normally.

# 5. Verify Ollama is running
# Default: http://127.0.0.1:11434
# Or custom host via OLLAMA_HOST environment variable

What poetry install does

  1. Creates a fresh virtual environment (if one does not already exist).
  2. Installs the exact dependency versions defined in pyproject.toml.
  3. Sets up a poetry.lock file to guarantee reproducible installs.

NOTE: The poetry run command automatically activates the environment for a single command, so you can skip poetry shell if you prefer a one-liner.

Quick Start

Running the Script

The recommended way to run the script is via Poetry. Choose one of the two approaches below:

Option 1 – Run directly with Poetry

poetry run python scripts/mcp_interactive.py

Option 2 – Activate the Poetry shell first

poetry shell
python scripts/mcp_interactive.py

Both commands start the virtual environment automatically and execute the mcp_interactive.py script from the scripts directory.

Basic Workflow

  1. Check Status (Option 1): Verify Ollama connection and available models
  2. Start Server (Option 2): Launch the MCP server in the background
  3. Run Commands (Option 8): Execute MCP tools interactively
  4. View Logs (Option 4): Monitor server output and errors
  5. Stop Server (Option 3): Gracefully shutdown the server

The interactive menu provides 9 main options:

1. Check MCP Server Status

Displays comprehensive server and Ollama connection information:

  • Server Status: Running/Not Running with PID
  • PID File Location: Path to the PID file in tmp/ directory
  • Ollama Connection: Host URL and connection status
  • Available Models: Count and list of first 5 models

Example Output: 

============================================================
SERVER STATUS
============================================================
✓ Server is RUNNING (PID: 12345)
  PID File: C:\myCode\gitHub\mcp-ollama-python\tmp\.mcp_ollama_server.pid

Ollama Connection:
  Host: http://127.0.0.1:11434
  Status: ✓ Connected
  Available Models: 21
  Models: llama3.1:latest, qwen3-vl:latest, glm4:latest, phi4:latest, llava:latest
           ... and 16 more
============================================================

2. Start Server

Launches the MCP server as a background process with:

  • Automatic Cleanup: Removes stale pipe files before starting
  • Environment Variables: Applies custom environment configuration
  • Logging: Redirects stdout/stderr to log files
  • Process Isolation: Uses subprocess with proper signal handling
  • PID Management: Creates PID file for process tracking

Features: - Prevents duplicate server instances - Creates pipe file descriptors for graceful shutdown - Windows-specific process group creation - Automatic log file creation in logs/ directory

3. Stop Server

Gracefully stops the running MCP server:

  • Pipe Closure: Closes pipe file descriptors to signal shutdown
  • SIGTERM: Sends termination signal for graceful exit
  • Force Shutdown: Uses platform-specific force kill if needed (5-second timeout)
  • Cleanup: Removes PID files and stale pipe files
  • Verification: Confirms process termination

Shutdown Process: 1. Close pipe file descriptor 2. Send SIGTERM signal 3. Wait up to 5 seconds for graceful shutdown 4. Force terminate if still running (Windows: psutil, Unix: SIGKILL) 5. Clean up all temporary files

4. View Server Logs

Displays server log files with detailed information:

  • Standard Output Log: logs/mcp_ollama_server.log
  • Error Log: logs/mcp_ollama_server_error.log
  • File Sizes: Shows log file sizes for debugging
  • UTF-8 Encoding: Handles encoding issues gracefully

Features: - Distinguishes between empty and missing log files - Shows file paths for manual inspection - Error handling for file read operations

5. List Server Commands and Arguments

Discovers and displays all available MCP tools:

  • Tool Discovery: Uses autoloader to find all registered tools
  • Detailed Information: Shows name, description, and arguments
  • Argument Details: Displays type, requirement status, and descriptions
  • Schema Inspection: Shows complete input schema for each tool

Example Output: 

Found 8 tools:

1. ollama_list
   Description: List all available Ollama models
   Arguments:
     * format (string): Output format (default: json)

2. ollama_chat
   Description: Interactive chat with Ollama models
   Arguments:
     * model (string): Name of the model to use
     * messages (array): Array of chat messages
       format (string): Output format (default: json)

6. Manage Environment Variables

Submenu for comprehensive environment variable management:

Sub-options: 1. View current environment variables: Display custom and system variables 2. Add/Update environment variable: Set or modify variables 3. Remove environment variable: Delete custom variables 4. Reset to defaults: Clear all custom variables 5. Back to main menu: Return to main menu

Common Variables: - OLLAMA_HOST: Ollama server URL (default: http://127.0.0.1:11434) - OLLAMA_API_KEY: API key for Ollama (if required) - OLLAMA_MODELS: Custom models directory

Persistence: Variables are saved to tmp/.mcp_env_vars.json

7. View Current Environment Variables

Displays environment configuration:

  • Custom Variables: Variables set through the script
  • System Variables: Ollama-related system environment variables
  • Suggestions: Common variables you might want to set

8. Run MCP Command

Interactive command execution with guided parameter input:

Workflow: 1. Tool Selection: Choose from available MCP tools 2. Parameter Input: Guided prompts for each required/optional parameter 3. Format Selection: Choose JSON or Markdown output 4. Execution: Run the command with provided parameters 5. Result Display: Show formatted output

Special Handling: - Chat Messages: Simplified input for chat message arrays - Arrays: Comma-separated value input - Objects: JSON format input with validation - Required vs Optional: Clear indicators for parameter requirements

Example Session: 

Available commands (8):

1. ollama_list
   List all available Ollama models

Select command number: 1

Arguments:
  format (string) [OPTIONAL]
  Output format (default: json)
  Enter value: json

Output format:
  1. JSON
  2. Markdown
Select format (1 or 2, default: 1): 1

============================================================
EXECUTING COMMAND...
============================================================

RESULT:
{
  "models": [...]
}

✓ Command executed successfully.

9. Exit

Cleanly exits the application.

File Structure

The script manages files in organized directories:

mcp-ollama-python/
├── scripts/
│   └── mcp_interactive.py          # Main script
├── tmp/                             # Temporary files (auto-created)
│   ├── .mcp_ollama_server.pid      # Server process ID
│   ├── .mcp_ollama_server_*.pipe   # Pipe file descriptors
│   └── .mcp_env_vars.json          # Persistent environment variables
├── logs/                            # Log files (auto-created)
│   ├── mcp_ollama_server.log       # Standard output
│   └── mcp_ollama_server_error.log # Error output
└── src/
    └── mcp_ollama_python/           # MCP server package

Directory Management

  • Automatic Creation: tmp/ and logs/ directories are created automatically
  • Cleanup: Stale pipe files are automatically removed
  • Persistence: Environment variables persist across sessions

Configuration

Environment Variables

Set custom environment variables through the menu (Option 6) or directly in tmp/.mcp_env_vars.json:

{
  "OLLAMA_HOST": "http://ai:11434/",
  "OLLAMA_API_KEY": "your-api-key-here"
}

Default Configuration

  • Ollama Host: http://127.0.0.1:11434 (or OLLAMA_HOST env var)
  • Log Directory: logs/ (relative to project root)
  • Temp Directory: tmp/ (relative to project root)
  • Server Timeout: 5 seconds for graceful shutdown

Usage Examples

Example 1: Start Server and Check Status

# Run the script
python mcp_interactive.py

# Select option 2 to start server
Select option (1-9): 2

# Wait for confirmation
✓ Server started successfully (PID: 12345)

# Select option 1 to check status
Select option (1-9): 1

# View status information
✓ Server is RUNNING (PID: 12345)
Ollama Connection: ✓ Connected
Available Models: 21

Example 2: Configure Custom Ollama Host

# Select option 6 (Manage environment variables)
Select option (1-9): 6

# Select option 2 (Add/Update environment variable)
Select option (1-5): 2

# Enter variable name
Enter variable name: OLLAMA_HOST

# Enter value
Enter value for OLLAMA_HOST: http://ai:11434/

✓ Set OLLAMA_HOST = http://ai:11434/

Example 3: Execute Chat Command

# Select option 8 (Run MCP command)
Select option (1-9): 8

# Select ollama_chat
Select command number: 2

# Enter model name
model (string) [REQUIRED]
Enter value: llava:latest

# Enter message
messages (array) [REQUIRED]
Enter your message: Explain what MCP is

# Select output format
Select format (1 or 2, default: 1): 2

# View result in Markdown format
RESULT:
MCP (Model Context Protocol) is a standardized protocol...

✓ Command executed successfully.

Example 4: View Logs

# Select option 4 (View server logs)
Select option (1-9): 4

# View log content
Log file: C:\myCode\gitHub\mcp-ollama-python\logs\mcp_ollama_server.log

Log content:
Starting Ollama MCP Server...
Server started successfully!
Waiting for MCP client connections...

File Information:
  Log file size: 156 bytes
  Error log file size: 0 bytes

Technical Details

Process Management

PID Validation: - Uses psutil.Process() to verify process existence - Checks command line for mcp_ollama_python to confirm identity - Automatically cleans up stale PID files

Process Creation: 

# Windows-specific flags
creationflags = subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.CREATE_NO_WINDOW

# Unix: start_new_session=True
process = subprocess.Popen(
    [sys.executable, "-m", "mcp_ollama_python"],
    stdin=stdin_read,
    stdout=log_file,
    stderr=error_log_file,
    start_new_session=True,
    creationflags=creationflags  # Windows only
)

Pipe File Management

Purpose: Enable graceful server shutdown by closing stdin

Implementation: 1. Create pipe: stdin_read, stdin_write = os.pipe() 2. Pass read end to subprocess 3. Store write end in tmp/.mcp_ollama_server_{pid}.pipe 4. Close write end during shutdown to signal EOF

Stale File Cleanup

Automatic Cleanup: - Runs on server start, stop, and status check - Removes pipe files for non-existent processes - Removes pipe files for processes that aren't MCP servers - Handles invalid filename formats gracefully

Async Command Execution

Architecture: 

async def execute_command():
    ollama_client = OllamaClient()
    server = OllamaMCPServer(ollama_client)

    # Get tools and execute
    tools_result = await server.handle_list_tools()
    result = await server.handle_call_tool(tool_name, args)

    # Cleanup
    await ollama_client.client.aclose()

asyncio.run(execute_command())

Cross-Platform Compatibility

Windows: - Uses psutil.Process.terminate() for force shutdown - Requires CREATE_NEW_PROCESS_GROUP flag - No SIGKILL signal available

Unix/Linux: - Uses signal.SIGTERM for graceful shutdown - Uses signal.SIGKILL for force shutdown - Standard signal handling

Troubleshooting

Common Issues

1. Server Won't Start

Symptoms: Server fails to start, error in logs

Solutions: - Check if Ollama is running: curl http://localhost:11434/api/tags - Verify Python version: python --version (requires 3.10+) - Ensure Poetry dependencies are installed: poetry install - Check for port conflicts - Review error log: logs/mcp_ollama_server_error.log - Verify you're running with Poetry: poetry run python scripts/mcp_interactive.py

2. Stale PID File

Symptoms: Script says server is running but it's not

Solutions: - The script automatically detects and cleans stale PID files - If issue persists, manually delete: tmp/.mcp_ollama_server.pid - Run status check (Option 1) to trigger cleanup

3. Cannot Connect to Ollama

Symptoms: "Cannot connect" error when checking status

Solutions: - Verify Ollama is running: ollama list - Check OLLAMA_HOST environment variable - Test connection: curl http://localhost:11434/api/tags - Configure custom host via Option 6

4. Permission Denied on Windows

Symptoms: Cannot terminate process or delete files

Solutions: - Run as Administrator - Close any file handles to log files - Wait a few seconds and try again - Check antivirus software isn't blocking

5. Logs Are Empty

Symptoms: Log files exist but contain no content

Solutions: - Server may still be starting (wait a few seconds) - Check file permissions on logs/ directory - Verify server is actually running (Option 1) - Check error log for startup issues

6. Command Execution Fails

Symptoms: MCP command returns error

Solutions: - Verify model name is correct: Use Option 5 to list available tools - Check required parameters are provided - Ensure Ollama has the specified model: ollama list - Review command syntax in tool description

7. Poetry-Specific Issues

Symptom Cause Fix
poetry: command not found Poetry is not installed or the binary is not on the PATH. Install Poetry (e.g. curl -sSL https://install.python-poetry.org | python3 -) and add ~/.local/bin (or the install prefix) to your PATH. Verify with poetry --version.
Python version mismatch (3.10+ required) The current interpreter is older than the version required by the project. Switch to a supported Python version (e.g., pyenv install 3.12.0 && pyenv local 3.12.0) or update the python key in pyproject.toml and re-run poetry env use <python>.
poetry.lock conflicts or stale lock file The lock file was generated with a different Poetry version or after changes to dependencies. Delete the lock file (rm poetry.lock), run poetry lock to regenerate it, and then poetry install. If the conflict is due to a specific dependency, adjust the version specifier in pyproject.toml before locking again.
Virtual environment issues (env not created / missing packages) Poetry is unable to create or activate the virtual environment, often due to missing system packages or an incorrectly configured setting. Ensure build tools are installed (sudo apt install build-essential libffi-dev python3-dev on Debian/Ubuntu, or Visual C++ Build Tools on Windows). If the env exists but is corrupted, delete it (poetry env remove <name>), then run poetry install to recreate.

Debug Mode

For detailed debugging:

  1. Check Process: ps aux | grep mcp_ollama_python (Unix) or Task Manager (Windows)
  2. Manual Cleanup: Delete files in tmp/ directory
  3. View Raw Logs: Open log files directly in text editor
  4. Test Ollama: curl http://localhost:11434/api/tags

Getting Help

If issues persist:

  1. Check server logs (Option 4)
  2. Verify Ollama connection (Option 1)
  3. Review environment variables (Option 7)
  4. Check GitHub issues for similar problems
  5. Provide log files when reporting issues

Advanced Usage

Custom Ollama Host

For remote Ollama servers:

# Set via environment variable management (Option 6)
OLLAMA_HOST=http://remote-server:11434/

Batch Operations

While the script is interactive, you can script operations:

# Start server programmatically
python -c "from mcp_interactive import MCPInteractive; m = MCPInteractive(); m.start_server()"

Integration with Other Tools

The MCP server can be used by: - Claude Desktop - Cline VSCode Extension - Custom MCP clients - API integrations

Security Considerations

  • API Keys: Store sensitive keys in environment variables, not in code
  • Network Access: Configure firewall rules for Ollama host
  • Process Isolation: Server runs in separate process for security
  • Log Files: May contain sensitive information, protect accordingly

Performance Tips

  • Model Selection: Smaller models respond faster
  • Log Rotation: Periodically clear old log files
  • Resource Monitoring: Check system resources if server is slow
  • Network Latency: Use local Ollama instance for best performance

License

This script is part of the mcp-ollama-python project. See the main project LICENSE file for details.

Contributing

Contributions are welcome! Please see the main project CONTRIBUTING.md for guidelines.

Last Updated: December 2025 Version: 1.0 Maintained By: mcp-ollama-python contributors