Claude Desktop

Claude Desktop supports MCP servers through its configuration system. This guide will help you set up your Arcade MCP server 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:

# 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 MCP 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 MCP server to the configuration file:

{
  "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:

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

2. Multiple Servers

You can configure multiple MCP servers:

{
  "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 MCP server:

{
  "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:

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

Debug Mode

Enable debug logging for troubleshooting:

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

Tool Discovery Options

Auto-Discovery

Automatically discover tools in the current directory:

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

Specific Package

Load a specific Arcade package:

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

All Installed Packages

Discover all installed Arcade packages:

{
  "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 tools are properly decorated with @tool
Check the working directory is correct
Enable debug mode to see tool discovery logs
Ensure no import errors in your tool files

Authentication Errors

Verify environment variables are set correctly
Check API keys 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:

{
  "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 tool to verify it's working

Best Practices

Use Virtual Environments: Isolate dependencies for each MCP server
Manage Secrets Securely: Use environment files or secret management tools
Enable Debug Logging: During development to troubleshoot issues
Organize Tools: Group related tools in separate servers
Document Your Tools: Use clear descriptions and type annotations

Example: Complete Setup

Using Arcade CLI (Recommended)

The fastest way to get started:

# 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 project structure:

my-mcp-project/
 .env
 requirements.txt
 tools.py

Create tools.py:

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:

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

Restart Claude Desktop and your tools will be available!