arcade-mcp/libs/arcade-mcp-server/docs/clients/claude.md

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

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

Tools Not Available

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

Authentication Errors

1. Verify environment variables are set correctly
2. Check API keys and tokens are valid
3. 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

1. Save your configuration file
2. Restart Claude Desktop
3. Look for your server in Claude's interface
4. Try using a simple tool to verify it's working

Best Practices

1. Use Virtual Environments: Isolate dependencies for each MCP server
2. Manage Secrets Securely: Use environment files or secret management tools
3. Enable Debug Logging: During development to troubleshoot issues
4. Organize Tools: Group related tools in separate servers
5. 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:

1. Create your project structure:

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

2. 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__": {}}, {})

3. Configure Claude Desktop:

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

4. Restart Claude Desktop and your tools will be available!