MCP Redmine

Serveur MCP (Model Context Protocol) pour piloter une instance Redmine depuis Claude Desktop ou Claude CLI, via l'API REST de Redmine.

Prérequis

• Python 3.10+ (le code utilise la syntaxe d'union X | None).
• Une instance Redmine avec l'API REST activée (Administration → Configuration → API) et une clé API.

Installation

# 1. Cloner le projet
git clone https://github.com/NeveuGregor/mcp-redmineApi.git
cd mcp-redmineApi

# 2. Environnement virtuel
python3 -m venv venv
source venv/bin/activate          # Windows : venv\Scripts\activate

# 3. Dépendances
pip install -r requirements.txt

# 4. Configuration
cp .env.example .env              # puis éditez .env (URL + clé API)

# 5. Smoke-test contre votre instance
python3 test_connection.py

Clé API Redmine

Mon compte → Clé d'accès API → Afficher, puis collez-la dans .env (REDMINE_API_KEY=...).

Configuration

Variables d'environnement (.env)

Variable	Obligatoire	Description
REDMINE_URL	✅	URL de base (doit commencer par http:// ou https://)
REDMINE_API_KEY	✅	Clé d'accès API
REDMINE_DEFAULT_PROJECT_ID	—	Projet par défaut pour la création d'issues
REDMINE_TIMEOUT	—	Timeout HTTP en secondes (défaut : 30)
DEBUG	—	Logs de debug sur stderr (défaut : false)
REDMINE_UPLOAD_DIRS	—	Répertoires autorisés pour l'upload (CSV). Vide = upload désactivé

⚠️ Sécurité upload : REDMINE_UPLOAD_DIRS n'autorise que les répertoires de confiance. Le serveur peut lire et téléverser tout fichier sous ces chemins. Laissé vide, l'attachement de fichiers est refusé (comportement par défaut sûr).

Claude CLI (Claude Code)

# Scope local (projet courant) ou user (tous vos projets)
claude mcp add redmine --scope user python3 -m src.main --cwd /chemin/absolu/vers/redmine-mcp

# Vérifier
claude mcp list

Claude Desktop

Dans claude_desktop_config.json :

{
  "mcpServers": {
    "redmine": {
      "command": "python3",
      "args": ["-m", "src.main"],
      "cwd": "/chemin/absolu/vers/redmine-mcp"
    }
  }
}

Emplacement du fichier : macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\, Linux ~/.config/Claude/.

Note : le package Python s'appelle src ; le serveur se lance via python3 -m src.main depuis la racine du projet (champ cwd).

Outils disponibles (7)

create_issue(subject, description, ...)

Crée une demande. Paramètres : subject, description, project_id, priority_id (1=Basse … 5=Immédiate), tracker_id, assigned_to_id, parent_issue_id, files (chemins — nécessite REDMINE_UPLOAD_DIRS), estimated_hours.

update_issue(issue_id, ...)

Met à jour une issue. Paramètres : issue_id*, subject, description, status_id, priority_id, assigned_to_id, estimated_hours, notes.

search_issues(...)

Recherche d'issues. Paramètres : project_id, assigned_to_id, status_id, tracker_id, subject, limit (défaut 25), offset.

Par défaut Redmine ne renvoie que les issues ouvertes. Pour élargir, passez status_id à "open", "closed" ou "*" (toutes), ou un id de statut précis. Le résultat indique « X affichées sur N au total » en cas de troncature.

list_projects()

Liste tous les projets accessibles (pagination suivie automatiquement).

list_users(limit=None)

Liste les utilisateurs (tous par défaut ; limit borne l'affichage).

add_time_entry(hours, comments, ...)

Saisie de temps. Paramètres : hours, comments, issue_id ou project_id, spent_on (YYYY-MM-DD), activity_id.

get_metadata()

Trackers, statuts et utilisateurs (ids/noms) pour alimenter les autres outils.

* = paramètre obligatoire

Développement & tests

Les tests unitaires mockent l'API HTTP (respx) — aucune instance Redmine requise.

# Dépendances de dev
pip install -r requirements-dev.txt

# Lancer la suite
python3 -m pytest

# Smoke-test contre une vraie instance (lit .env)
python3 test_connection.py

# Vérifier la config
python3 -c "from src.config import config; print(config.redmine_url)"

Dépannage

Symptôme	Piste
Accès refusé (403)	Clé API invalide ou permissions Redmine insuffisantes
Ressource introuvable (404)	Mauvais id d'issue/projet
Données invalides (422)	Champ obligatoire manquant (le détail Redmine est remonté)
Erreur réseau	URL injoignable / timeout — augmentez REDMINE_TIMEOUT
Upload désactivé	Définissez REDMINE_UPLOAD_DIRS

Mode debug (logs détaillés sur stderr) : DEBUG=true python3 -m src.main.

Architecture

src/
  main.py            point d'entrée (def main)
  server.py          enregistrement des outils + gestion d'erreurs centralisée
  config.py          configuration (.env) validée par pydantic
  errors.py          RedmineError (status_code, details)
  models.py          modèles Pydantic des entités Redmine
  redmine_client.py  client HTTP (httpx) + parsing
  tools/             un module par outil
tests/               suite pytest (mock respx)