Claude Desktop

Claude Desktop supports servers through its configuration system. This guide will help you set up your Arcade with Claude Desktop.

Prerequisites

Claude Desktop installed
Python 3.10+ installed
arcade-mcp package installed (pip install arcade-mcp)

Quick setup with Arcade CLI

The easiest way to configure Claude Desktop is with the arcade configure command:

Terminal


# Install Arcade CLI
uv pip install arcade-mcp
 
# Create a new server (optional, if you don't have one yet)
arcade new my_server
cd my_server
 
# Configure Claude Desktop to use your local server
arcade configure claude --from-local

This automatically updates your Claude Desktop configuration file with the correct settings.

Manual configuration

Claude Desktop reads server configurations from its settings file. The location varies by platform:

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

Basic setup

1. Create or edit configuration

Add your server to the configuration file:

JSON


{
  "mcpServers": {
    "arcade-tools": {
      "command": "arcade",
      "args": ["mcp", "stdio"],
      "cwd": "/path/to/your/project"
    }
  }
}

Note: If you don’t have the Arcade CLI installed globally, you can use the module directly:

JSON


{
  "mcpServers": {
    "arcade-tools": {
      "command": "arcade",
      "args": ["-m", "arcade_mcp_server", "stdio"],
      "cwd": "/path/to/your/project"
    }
  }
}

2. Multiple servers

You can configure multiple servers:

JSON


{
  "mcpServers": {
    "github-tools": {
      "command": "arcade",
      "args": ["mcp", "stdio", "--tool-package", "github"],
      "env": {
        "GITHUB_TOKEN": "your-github-token"
      }
    },
    "slack-tools": {
      "command": "arcade",
      "args": ["mcp", "stdio", "--tool-package", "slack"],
      "env": {
        "SLACK_BOT_TOKEN": "your-slack-token"
      }
    },
    "custom-tools": {
      "command": "arcade",
      "args": ["mcp", "stdio"],
      "cwd": "/path/to/custom/tools"
    }
  }
}

Advanced configuration

Environment variables

Pass environment variables to your server:

JSON


{
  "mcpServers": {
    "my-tools": {
      "command": "arcade",
      "args": ["-m", "arcade_mcp_server", "stdio", "--env-file", ".env"],
      "cwd": "/path/to/project",
      "env": {
        "ARCADE_API_KEY": "your-api-key",
        "DATABASE_URL": "postgresql://localhost/mydb",
        "DEBUG": "true"
      }
    }
  }
}

Custom Python environment

Use a specific Python virtual environment:

JSON


{
  "mcpServers": {
    "my-tools": {
      "command": "/path/to/venv/bin/arcade",
      "args": ["mcp", "stdio"],
      "cwd": "/path/to/project"
    }
  }
}

Debug mode

Enable debug logging for troubleshooting:

JSON


{
  "mcpServers": {
    "my-tools": {
      "command": "arcade",
      "args": ["mcp", "stdio", "--debug"],
      "cwd": "/path/to/project"
    }
  }
}

Tool discovery options

Auto-discovery

Automatically discover in the current directory:

JSON


{
  "mcpServers": {
    "local-tools": {
      "command": "arcade",
      "args": ["mcp", "stdio"],
      "cwd": "/path/to/tools/directory"
    }
  }
}

Specific package

Load a specific Arcade package:

JSON


{
  "mcpServers": {
    "github": {
      "command": "arcade",
      "args": ["-m", "arcade_mcp", "stdio", "--tool-package", "github"]
    }
  }
}

All installed packages

Discover all installed Arcade packages:

JSON


{
  "mcpServers": {
    "all-arcade-tools": {
      "command": "arcade",
      "args": ["-m", "arcade_mcp", "stdio", "--discover-installed"]
    }
  }
}

Troubleshooting

Common issues

Server not starting

Check the command path is correct
Verify arcade is in your PATH (or use full path to arcade binary)
Ensure arcade-mcp is installed (uv pip install arcade-mcp)
Check file permissions on the working directory

Tools not available

Verify are properly decorated with @tool
Check the working directory is correct
Enable debug mode to see discovery logs
Ensure no import errors in your files

Authentication errors

Verify environment variables are set correctly
Check and tokens are valid
Ensure proper escaping of special characters in JSON

Viewing logs

When using stdio transport, logs are sent to stderr. To capture logs:

JSON


{
  "mcpServers": {
    "my-tools": {
      "command": "arcade",
      "args": ["mcp", "stdio", "--debug"],
      "cwd": "/path/to/project",
      "stderr": "/tmp/arcade-mcp.log"
    }
  }
}

Testing your configuration

Save your configuration file
Restart Claude Desktop
Look for your server in Claude’s interface
Try using a simple to verify it’s working

Best practices

Use virtual environments: Isolate dependencies for each server
Manage secrets securely: Use environment files or secret management
Enable debug logging: During development to troubleshoot issues
Organize : Group related tools in separate servers
Document your : Use clear descriptions and type annotations

Example: Complete setup

Using Arcade CLI (recommended)

The fastest way to get started:

Terminal


# Create a new server with example tools
arcade new my_server
cd my_server
 
# Configure Claude Desktop
arcade configure claude --from-local
 
# Restart Claude Desktop and your tools will be available!

Manual setup

If you prefer to set up manually:

Create your structure:

PLAINTEXT


my-mcp-project/
├── .env
├── requirements.txt
└── tools.py

Create tools.py:

Python


from arcade_mcp_server import tool
from typing import Annotated
 
@tool
def greet(name: Annotated[str, "Name to greet"]) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"
 
@tool
def calculate(
    expression: Annotated[str, "Math expression"]
) -> Annotated[float, "Result"]:
    """Calculate a mathematical expression."""
    return eval(expression, {"__builtins__": {}}, {})

Configure Claude Desktop:

JSON


{
  "mcpServers": {
    "my-project": {
      "command": "arcade",
      "args": ["mcp", "stdio", "--debug"],
      "cwd": "/path/to/my-mcp-project"
    }
  }
}

Restart Claude Desktop and your will be available!