Local Stdio Deployment

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dvlpjrs/guMCP/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

• Each server runs as a separate process
• Communication happens through stdin/stdout
• Suitable for single-user, local environments
• Works with Claude Desktop, Cline, and other local MCP clients

​

Prerequisites

git clone https://github.com/dvlpjrs/guMCP.git
cd guMCP

# Create the virtual environment
python -m venv venv

# Activate it (choose the appropriate command for your OS)
# On Unix/macOS:
source venv/bin/activate

# On Windows (Command Prompt):
venv\Scripts\activate

# On Windows (PowerShell):
.\venv\Scripts\Activate.ps1

# On Windows (Git Bash):
source venv/Scripts/activate

pip install -r requirements.txt

cp .env.example .env
# Edit .env with your API keys and configuration

​

Running a Server

​

Basic Usage

python src/servers/local.py --server=<server-name>

​

Example: Simple Tools Server

python src/servers/local.py --server=simple-tools-server

​

Example: Google Sheets Server

python src/servers/local.py --server=gsheets

​

With User ID

python src/servers/local.py --server=simple-tools-server --user-id=myuser

​

Available Servers

• A server object (server factory)
• A get_initialization_options function

python src/servers/local.py --server=invalid

​

Testing with the Local MCP Client

python tests/clients/LocalMCPTestClient.py --server=simple-tools-server

• Starts the server automatically
• Connects via stdio
• Provides an interactive testing interface
• Useful for development and debugging

​

Configuration for Claude Desktop

​

macOS/Linux

{
  "mcpServers": {
    "gsheets": {
      "command": "/path/to/guMCP/venv/bin/python",
      "args": [
        "/path/to/guMCP/src/servers/local.py",
        "--server=gsheets"
      ],
      "env": {
        "GOOGLE_CREDENTIALS_PATH": "/path/to/credentials.json"
      }
    }
  }
}

​

Windows

{
  "mcpServers": {
    "gsheets": {
      "command": "C:\\path\\to\\guMCP\\venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\guMCP\\src\\servers\\local.py",
        "--server=gsheets"
      ],
      "env": {
        "GOOGLE_CREDENTIALS_PATH": "C:\\path\\to\\credentials.json"
      }
    }
  }
}

​

How It Works

1. Loads the specified server module from src/servers/<server-name>/main.py
2. Validates required attributes (server and get_initialization_options)
3. Creates a server instance with the optional user ID
4. Starts the stdio transport using mcp.server.stdio.stdio_server()
5. Runs the server with the read/write streams

​

Key Features

• Dynamic server loading: Servers are loaded dynamically by name
• User context: Optional --user-id parameter for multi-user scenarios
• Error handling: Provides helpful error messages and lists available servers
• Logging: Comprehensive logging for debugging

​

Troubleshooting

​

Server Not Found

1. Check that the server directory exists in src/servers/
2. Verify the directory contains a main.py file
3. Run with an invalid server name to see the list of available servers

​

Import Errors

1. Ensure your virtual environment is activated
2. Verify all dependencies are installed: pip install -r requirements.txt
3. Check that you’re running from the guMCP root directory

​

Authentication Errors

1. Verify your .env file is configured correctly
2. Check that API keys and credentials are valid
3. For OAuth servers, ensure credentials files are in the correct location
4. See Environment Setup for configuration details

​

Next Steps

• Remote SSE Deployment - Run servers remotely
• Environment Setup - Configure environment variables
• Server Documentation - Learn about available servers