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:

```bash
# 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:

```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 MCP 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 MCP 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 tools 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

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:

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

```bash
# 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`:
```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__": {}}, {})
```

3. Configure Claude Desktop:
```json
{
  "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!