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:

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

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

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

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

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

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

### Specific Package

Load a specific Arcade package:

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

### All Installed Packages

Discover all installed Arcade packages:

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

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