Quick Start

Get up and running with guMCP in minutes

This guide will help you quickly set up and run your first guMCP server.

Make sure you’ve completed the Installation steps before proceeding.

Understanding guMCP Architecture

guMCP supports two transport methods:

• SSE (Server-Sent Events) - Remote servers accessible via HTTP
• Stdio - Local servers that communicate via standard input/output

For most use cases, we recommend starting with SSE servers as they provide a single URL to access all available servers.

Running Your First Server

1. Start the SSE development server

   From the project root directory, run:

   ./start_sse_dev_server.sh
   

   This script will:

   1. Load environment variables from your .env file
   2. Set default host (0.0.0.0) and port (8000) if not configured
   3. Kill any existing process on the port
   4. Start the guMCP server

   You should see output like:

   Loading environment variables from .env file
   Starting guMCP development server on 0.0.0.0:8000
   INFO:     Started server process
   INFO:     Waiting for application startup.
   INFO:     Application startup complete.
   INFO:     Uvicorn running on http://0.0.0.0:8000
   
2. Test the server with the MCP client

   Open a new terminal window (keep the server running in the first), activate your virtual environment, and run:

   python tests/clients/RemoteMCPTestClient.py --endpoint=http://localhost:8000/simple-tools-server/local
   

   This launches an interactive MCP client connected to the simple-tools-server.

   Make sure you have set your ANTHROPIC_API_KEY in your .env file for the test client to work.

3. Try a simple command

   In the test client, you can now interact with the MCP server through Claude. Try asking:

   What tools are available?
   

   Or test a simple tool:

   Add 5 and 3
   

   Type quit or press Ctrl+C to exit the client.

Running Different Servers

Available Servers

guMCP includes multiple server implementations:

• simple-tools-server - Basic tools for testing
• gsheets - Google Sheets integration
• gmail - Gmail integration
• gdocs - Google Docs integration
• gdrive - Google Drive integration
• gcalendar - Google Calendar integration
• slack - Slack integration
• outlook - Outlook integration
• airtable - Airtable integration
• linear - Linear integration
• attio - Attio CRM integration
• perplexity - Perplexity AI integration
• hubspot - HubSpot integration
• quickbooks - QuickBooks integration
• typeform - Typeform integration

SSE Server Access

When running the SSE server, all servers are accessible at:

http://localhost:8000/{server-name}/local

For example:

• http://localhost:8000/simple-tools-server/local
• http://localhost:8000/perplexity/local
• http://localhost:8000/slack/local

Running Stdio Servers

To run a specific server locally using stdio:

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

You can also use the local test client:

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

Configuring Authentication

Many servers require authentication before they can be used. Let’s configure the Perplexity server as an example:

1. Get your API key

   Sign up for a Perplexity API key at perplexity.ai

2. Run the authentication command

   python src/servers/perplexity/main.py auth
   

   You’ll be prompted to enter your Perplexity API key.

3. Test the authenticated server

   Start the SSE server and connect to the Perplexity endpoint:

   # In terminal 1
   ./start_sse_dev_server.sh
   
   # In terminal 2
   python tests/clients/RemoteMCPTestClient.py --endpoint=http://localhost:8000/perplexity/local
   

For OAuth-based servers (Google, Slack, etc.), see the individual server documentation in src/servers/{server-name}/README.md for authentication setup instructions.

Connecting to Claude Desktop

To use guMCP servers with Claude Desktop:

1. Start your SSE server

   ./start_sse_dev_server.sh
   
2. Configure Claude Desktop

   Open your Claude Desktop configuration file:

   macOS

   ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
3. Add the MCP server configuration

   Add your guMCP server to the configuration:

   {
     "mcpServers": {
       "simple-tools": {
         "command": "python",
         "args": [
           "/absolute/path/to/guMCP/src/servers/local.py",
           "--server=simple-tools-server"
         ]
       }
     }
   }
   

   Replace /absolute/path/to/guMCP with the actual path to your guMCP installation.

4. Restart Claude Desktop

   Restart Claude Desktop to load the new configuration. You should now see your MCP server available in Claude.

Common Use Cases

Running multiple servers simultaneously

The SSE server runs all servers at once. Simply start it and access different servers via their respective endpoints:

./start_sse_dev_server.sh

Then connect to any server:

• http://localhost:8000/simple-tools-server/local
• http://localhost:8000/perplexity/local
• http://localhost:8000/gsheets/local

Running on a custom port

Set the GUMCP_PORT environment variable:

GUMCP_PORT=3000 ./start_sse_dev_server.sh

Or add it to your .env file:

GUMCP_PORT=3000

Accessing from remote machines

By default, the server listens on 0.0.0.0, making it accessible from other machines on your network. To restrict to localhost only:

GUMCP_HOST=127.0.0.1 ./start_sse_dev_server.sh

Running in production

For production deployments, consider:

1. Setting ENVIRONMENT=production in your .env
2. Using a process manager like systemd or PM2
3. Running behind a reverse proxy (nginx, Caddy)
4. Enabling HTTPS with proper SSL certificates
5. Implementing rate limiting and authentication

See the Configuration guide for production settings.

Troubleshooting

Server won't start

Check if:

1. Your virtual environment is activated
2. All dependencies are installed: pip install -r requirements.txt
3. The port isn’t already in use by another application
4. Your .env file exists and is properly formatted

Authentication errors

For authentication issues:

1. Verify your API keys are correctly set in .env
2. Run the server-specific auth command (e.g., python src/servers/perplexity/main.py auth)
3. Check that OAuth credentials are stored in local_auth/credentials/
4. Ensure OAuth configuration files exist in local_auth/oauth_configs/

Test client connection failures

If the test client can’t connect:

1. Ensure the SSE server is running
2. Verify the endpoint URL is correct
3. Check that ANTHROPIC_API_KEY is set in your .env
4. Try accessing the endpoint in a browser to see if it responds

Import errors

If you see module import errors:

1. Make sure you’re running commands from the project root
2. Verify your virtual environment is activated
3. Try reinstalling dependencies: pip install -r requirements.txt --force-reinstall

Next Steps

Configuration

Learn about all configuration options and environment variables

Contributing

Contribute to guMCP by adding new servers or features