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-ai package installed (pip install arcade-ai)

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:

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

2. Multiple Servers

You can configure multiple MCP servers:

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

Advanced Configuration

Environment Variables

Pass environment variables to your MCP server:

{
  "mcp-servers": {
    "my-tools": {
      "command": "python",
      "args": ["-m", "arcade_mcp", "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:

{
  "mcp-servers": {
    "my-tools": {
      "command": "/path/to/venv/bin/python",
      "args": ["-m", "arcade_mcp", "stdio"],
      "cwd": "/path/to/project"
    }
  }
}

Debug Mode

Enable debug logging for troubleshooting:

{
  "mcp-servers": {
    "my-tools": {
      "command": "python",
      "args": ["-m", "arcade_mcp", "stdio", "--debug"],
      "cwd": "/path/to/project"
    }
  }
}

Tool Discovery Options

Auto-Discovery

Automatically discover tools in the current directory:

{
  "mcp-servers": {
    "local-tools": {
      "command": "python",
      "args": ["-m", "arcade_mcp", "stdio"],
      "cwd": "/path/to/tools/directory"
    }
  }
}

Specific Package

Load a specific Arcade package:

{
  "mcp-servers": {
    "github": {
      "command": "python",
      "args": ["-m", "arcade_mcp", "stdio", "--tool-package", "github"]
    }
  }
}

All Installed Packages

Discover all installed Arcade packages:

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

Troubleshooting

Common Issues

Server Not Starting

1. Check the command path is correct
2. Verify Python is in your PATH
3. Ensure arcade-ai is installed in the Python environment
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:

{
  "mcp-servers": {
    "my-tools": {
      "command": "python",
      "args": ["-m", "arcade_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

Here's a complete example setting up a project with custom tools:

1. Create your project structure:

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

2. Create tools.py:

from arcade_tdk 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:

{
  "mcp-servers": {
    "my-project": {
      "command": "python",
      "args": ["-m", "arcade_mcp", "stdio", "--debug"],
      "cwd": "/path/to/my-mcp-project"
    }
  }
}

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