# Plane MCP — Setup

## Prérequis

| Composant | Version min | Pour quoi |
|---|---|---|
| Claude Code | latest | Client |
| Node.js | 22+ | Transports HTTP |
| Python | 3.10+ | Transport stdio local |
| `uvx` | latest | Lancement du serveur stdio (`pip install uv` ou `brew install uv`) |

API key : générer depuis **Workspace Settings → API Tokens** dans l'instance Plane.

## Setup ADVMFR (utilisé ici)

Le projet utilise le **Local Stdio** (self-hosted) déjà configuré dans `.mcp.json` :

```json
{
  "mcpServers": {
    "plane": {
      "type": "stdio",
      "command": "uvx",
      "args": ["plane-mcp-server", "stdio"],
      "env": {
        "PLANE_API_KEY": "<token>",
        "PLANE_WORKSPACE_SLUG": "advmfr",
        "PLANE_BASE_URL": "https://projects.elevaseo.app"
      }
    }
  }
}
```

Le fichier `.claude/settings.local.json` active explicitement le serveur :

```json
{
  "enabledMcpjsonServers": ["plane"],
  "enableAllProjectMcpServers": true
}
```

## Variables d'environnement

| Variable | Requis | Rôle |
|---|---|---|
| `PLANE_API_KEY` | oui | Token API workspace |
| `PLANE_WORKSPACE_SLUG` | oui | Slug du workspace (ici `advmfr`) |
| `PLANE_BASE_URL` | self-hosted uniquement | URL API self-hosted (défaut cloud : `https://api.plane.so`) |

## Autres méthodes de setup (référence)

### HTTP OAuth (Plane Cloud)

```bash
claude mcp add --transport http plane https://mcp.plane.so/http/mcp
# puis /mcp dans Claude Code pour l'auth OAuth navigateur
```

### HTTP PAT (CI / automation, Plane Cloud)

```bash
claude mcp add-json plane '{
  "type": "http",
  "url": "https://mcp.plane.so/http/api-key/mcp",
  "headers": {
    "Authorization": "Bearer <YOUR_API_KEY>",
    "X-Workspace-slug": "<YOUR_WORKSPACE_SLUG>"
  }
}'
```

### Scopes possibles avec `claude mcp add`

| Scope | Effet |
|---|---|
| `--scope local` | Local au projet (défaut) |
| `--scope project` | Stocké dans `.mcp.json` (versionable) — **utilisé ici** |
| `--scope user` | Disponible pour tous les projets de l'utilisateur |

## Vérification

```bash
claude mcp list           # liste les serveurs configurés
claude mcp get plane      # détails du serveur Plane
```

Dans Claude Code, `/mcp` affiche le statut de connexion et permet la réauthentification.

## Troubleshooting

```bash
# Debug verbeux
claude --mcp-debug

# Reset OAuth (cloud uniquement)
rm -rf ~/.mcp-auth

# Timeout étendu
MCP_TIMEOUT=10000 claude

# Vérification runtime
node --version
python --version
uvx --version
```

**Erreurs courantes**

- `command not found: uvx` → `brew install uv` ou `pip install uv`.
- `401 Unauthorized` → token expiré, en regénérer un dans Plane.
- `404` sur `PLANE_BASE_URL` → l'URL ne doit PAS contenir `/api/v1`, c'est la racine de l'instance.
- Serveur invisible dans `/mcp` → vérifier `enabledMcpjsonServers` dans `.claude/settings.local.json`.
- `404` sur un endpoint Plane (Initiatives, Teams, Workspace Features, Customers, Wiki) → attendu sur self-hosted CE ; ces features sont Cloud Business/Enterprise uniquement.

## Gestion

```bash
claude mcp remove plane   # retirer
```

Pour reconfigurer, éditer directement `.mcp.json`.