Skip to content

README.md

Latest commit

 

History

History
535 lines (398 loc) · 13.3 KB

README.md

File metadata and controls

535 lines (398 loc) · 13.3 KB

SimpleMCP Examples

This directory contains configuration examples and test scripts for connecting to SimpleMCP servers using different MCP transports.

Overview

SimpleMCP provides two MCP server implementations:

  1. STDIO Transport (mcp_server.py) - For local MCP clients (e.g., desktop applications)
  2. HTTP/SSE Transport (mcp_http_server.py) - For remote MCP clients (e.g., web apps, networked services)

This examples directory helps you:

  • Configure MCP clients to use SimpleMCP (with Claude Desktop examples)
  • Test both transport methods with example configurations
  • Test both servers programmatically with Python

Files in This Directory

File Description
claude_desktop_config_example.json Example STDIO configuration (using Claude Desktop as example)
claude_code_config_example.json Example HTTP/SSE configuration (using Claude Code as example)
test_mcp_client.py Python script to test both MCP servers
README.md This file - comprehensive documentation

Quick Start Guide

Option 1: STDIO Transport (Claude Desktop Example)

Local MCP clients typically use STDIO transport to communicate with MCP servers. This example uses Claude Desktop.

Step 1: Locate Your Client Config File

Example config file locations for Claude Desktop (other MCP clients may differ):

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Step 2: Edit the Config File

Add the SimpleMCP server configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "story-teller": {
      "command": "python",
      "args": [
        "/absolute/path/to/SimpleMCP/mcp_server.py"
      ]
    }
  }
}

Important: Replace /absolute/path/to/SimpleMCP with the actual absolute path to your SimpleMCP directory.

Step 3: Restart Your MCP Client

Close and reopen your MCP client to load the new configuration.

Step 4: Test the Connection

In your MCP client (example prompts for Claude-based clients):

  • "Can you list all the stories?"
  • "Please get me the story 'squirrel_and_owl'"
  • "What stories are available?"

Troubleshooting

If the server doesn't appear in your MCP client:

  1. Check the path: Ensure you used an absolute path, not a relative one
  2. Verify Python: Run python --version in terminal to ensure Python is accessible
  3. Install dependencies: In SimpleMCP directory, run pip install -r requirements.txt
  4. Test manually: Run python mcp_server.py to verify it starts without errors
  5. Check logs: Look at your MCP client's logs for error messages

Windows Users

On Windows, use one of these path formats:

"args": ["C:/Users/YourName/SimpleMCP/mcp_server.py"]

or

"args": ["C:\\\\Users\\\\YourName\\\\SimpleMCP\\\\mcp_server.py"]

Option 2: HTTP/SSE Transport (Remote Client Example)

MCP clients can connect to HTTP/SSE MCP servers for remote access. This example uses Claude Code CLI.

Step 1: Start the HTTP/SSE Server

First, navigate to your SimpleMCP directory and start the server:

cd /path/to/SimpleMCP
python mcp_http_server.py

You should see output like:

================================================================================
SimpleMCP HTTP/SSE Server v1.0.0
================================================================================
Server Name: story-teller-http
Transport: SSE (Server-Sent Events)
Host: 0.0.0.0
Port: 8000
SSE Endpoint: http://localhost:8000/sse
...

Optional: Use a custom port:

python mcp_http_server.py --port 8080

Step 2: Configure Your MCP Client

Add the server configuration to your MCP client. Example for Claude Code:

{
  "mcpServers": {
    "story-teller-http": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Config file locations vary by client:

  • Claude Code: See above paths
  • Custom clients: Check your client's documentation

Step 3: Test the Connection

Test your MCP client connection (example prompts for Claude-based clients):

  • "Can you list all the stories?"
  • "Please get me the story 'bear_loses_roar'"
  • "Show me the story about the turtle"

Troubleshooting

If the connection fails:

  1. Verify server is running: Check that you see the startup banner in your terminal
  2. Test health endpoint: Open http://localhost:8000/health in a browser
  3. Check port: Ensure the URL in your config matches the port the server is running on
  4. Firewall: Ensure your firewall isn't blocking port 8000
  5. Server logs: Check the terminal where the server is running for error messages

Using with curl

You can test the health endpoint with curl:

curl http://localhost:8000/health

Expected response:

{"status":"healthy","server":"story-teller-http","version":"1.0.0"}

Option 3: Programmatic Testing with Python

The test_mcp_client.py script lets you test both servers programmatically.

Prerequisites

Ensure you have the required dependencies:

pip install mcp httpx

Test STDIO Server

This will launch the STDIO server as a subprocess and test it:

python examples/test_mcp_client.py --stdio

Test HTTP/SSE Server

First, start the server in one terminal:

python mcp_http_server.py

Then, in another terminal, run the test:

python examples/test_mcp_client.py --http

Test with Custom URL

If you're running the HTTP server on a different port:

python examples/test_mcp_client.py --http --url http://localhost:8080/sse

Test Both Servers

You can test both servers at once:

# Make sure HTTP server is running first!
python examples/test_mcp_client.py --stdio --http

Understanding the Test Output

The test script will:

  1. Connect to the server
  2. List available tools
  3. Call list_stories to get all stories
  4. Call get_story with a valid story ID
  5. Call get_story with an invalid ID (to test error handling)

Example output:

================================================================================
Testing STDIO MCP Server (mcp_server.py)
================================================================================

Server script: /path/to/SimpleMCP/mcp_server.py

Connecting to STDIO server...
Connected successfully!

--------------------------------------------------------------------------------
Available Tools:
--------------------------------------------------------------------------------
  - list_stories: List all available stories...
  - get_story: Get a specific story by its ID...

--------------------------------------------------------------------------------
Test 1: Calling list_stories tool
--------------------------------------------------------------------------------
Result:
[
  {
    "id": "squirrel_and_owl",
    "title": "The Curious Squirrel and the Wise Owl"
  },
  ...
]

================================================================================
STDIO Server Test: SUCCESS
================================================================================

Available MCP Tools

Both servers provide the same two tools:

1. list_stories

Lists all available stories.

Parameters: None

Returns: JSON array of story objects with id and title fields

Example Response:

[
  {
    "id": "squirrel_and_owl",
    "title": "The Curious Squirrel and the Wise Owl"
  },
  {
    "id": "bear_loses_roar",
    "title": "The Bear Who Lost His Roar"
  },
  {
    "id": "turtle_wants_to_fly",
    "title": "The Turtle Who Wanted to Fly"
  },
  {
    "id": "lonely_firefly",
    "title": "The Lonely Firefly"
  },
  {
    "id": "rabbit_and_carrot",
    "title": "The Rabbit and the Magic Carrot"
  }
]

2. get_story

Retrieves a complete story by its ID.

Parameters:

  • story_id (string, required): The unique identifier of the story

Valid Story IDs:

  • squirrel_and_owl
  • bear_loses_roar
  • turtle_wants_to_fly
  • lonely_firefly
  • rabbit_and_carrot

Returns: Formatted story text with title, content, and metadata

Example Response:

# The Curious Squirrel and the Wise Owl

In a grand oak tree lived a wise old owl named Oliver...

[Full story text here]

---
Story ID: squirrel_and_owl

Error Handling: If you request a non-existent story ID, you'll receive an error message:

Error: Story 'invalid_id' not found

Comparison: STDIO vs HTTP/SSE

Feature STDIO (mcp_server.py) HTTP/SSE (mcp_http_server.py)
Transport STDIO (stdin/stdout) HTTP with Server-Sent Events
Best For Local desktop clients, subprocess tools Web clients, remote access, networked services
Setup Configured in client Server must be started separately
Network Local only (subprocess) Can be accessed over network
Port N/A 8000 (configurable)
Process Model Launched by client Long-running server
Health Check N/A Available at /health endpoint
Debugging Logs to stderr Logs to stderr + HTTP responses

Advanced Configuration

Environment Variables (HTTP/SSE Server)

The HTTP/SSE server supports these environment variables:

# Change default port
export MCP_HTTP_PORT=8080
python mcp_http_server.py

# Change default host
export MCP_HTTP_HOST=127.0.0.1
python mcp_http_server.py

# Combine with command-line args
python mcp_http_server.py --port 9000 --host 0.0.0.0

Using a Different Python Interpreter

If you need to use a specific Python version or virtual environment:

Claude Desktop (STDIO):

{
  "mcpServers": {
    "story-teller": {
      "command": "/path/to/venv/bin/python",
      "args": ["/absolute/path/to/SimpleMCP/mcp_server.py"]
    }
  }
}

Command Line (HTTP/SSE):

/path/to/venv/bin/python mcp_http_server.py

Running as a Background Service

To run the HTTP/SSE server as a background service:

Using nohup (Linux/macOS):

nohup python mcp_http_server.py > /tmp/mcp_server.log 2>&1 &

Using screen (Linux/macOS):

screen -dmS mcp python mcp_http_server.py
# To view: screen -r mcp

Using systemd (Linux): Create /etc/systemd/system/simplemcp.service:

[Unit]
Description=SimpleMCP HTTP/SSE Server
After=network.target

[Service]
Type=simple
User=yourusername
WorkingDirectory=/path/to/SimpleMCP
ExecStart=/usr/bin/python3 /path/to/SimpleMCP/mcp_http_server.py
Restart=on-failure

[Install]
WantedBy=multi-user.target

Then:

sudo systemctl enable simplemcp
sudo systemctl start simplemcp
sudo systemctl status simplemcp

Security Considerations

STDIO Server

  • Runs as a subprocess of the client
  • Inherits client's permissions
  • No network exposure
  • Generally safe for local use

HTTP/SSE Server

  • Default binding: 0.0.0.0 (all interfaces) on port 8000
  • Security note: This makes the server accessible from your network
  • For local-only: Use --host 127.0.0.1 to bind to localhost only
  • Authentication: Not implemented (add reverse proxy with auth if needed)
  • CORS: Enabled by default for browser clients
  • Production: Use a reverse proxy (nginx, Apache) with SSL/TLS

Recommended for Production:

# Local-only binding
python mcp_http_server.py --host 127.0.0.1 --port 8000

# Behind nginx with SSL
# Configure nginx to proxy to http://127.0.0.1:8000

Troubleshooting

Common Issues

1. "Module 'mcp' not found"

pip install -r requirements.txt

2. "Permission denied" when running scripts

chmod +x mcp_server.py mcp_http_server.py examples/test_mcp_client.py

3. "Address already in use" (HTTP/SSE server)

# Check what's using port 8000
lsof -i :8000  # macOS/Linux
netstat -ano | findstr :8000  # Windows

# Use a different port
python mcp_http_server.py --port 8080

4. "Cannot connect to server" (HTTP/SSE)

# Verify server is running
curl http://localhost:8000/health

# Check firewall
sudo ufw allow 8000  # Linux
# Or configure Windows Firewall

5. MCP client doesn't see the server

  • Use absolute paths in configuration
  • Restart your MCP client after config changes
  • Check your client's logs for errors
  • Verify Python is in system PATH
  • Test server manually first

Getting Help

If you encounter issues:

  1. Check the logs: Both servers log to stderr
  2. Test manually: Run the servers directly to see error messages
  3. Use test script: Run python examples/test_mcp_client.py to diagnose issues
  4. Check dependencies: Ensure all requirements are installed
  5. Review documentation: See main README.md for more details

Next Steps

  • Customize the stories: Edit stories/stories.json to add your own content
  • Add more tools: Extend mcp_server.py and mcp_http_server.py with new tools
  • Build integrations: Use SimpleMCP as a template for your own MCP servers
  • Deploy to production: Set up a reverse proxy and authentication

Additional Resources

Happy building with SimpleMCP!