# odoo-mpm-plugin

MPM Odoo ERP plugin for Claude Cowork — connects to mpmedia.odoo.com via XML-RPC with proxy-aware transport.

**Version:** 0.4.1
**Author:** Message Point Media
**Repo:** https://git.mpm.to/mpm/odoo-mpm-plugin
**CoWork Project:** CW-003 — Odoo V19 MCP Bridge

---

## Overview

This plugin bridges Claude Cowork to MPM's Odoo ERP instance at mpmedia.odoo.com. It runs a local MCP server (`odoo-mpm`) via `uv` that exposes read/write access across 13 modules: Products, Knowledge (with Templates), Contacts, Sales, CRM, Project (full CRUD + milestones + subtasks + chatter + followers + stages + checklists), Helpdesk, Purchase, Inventory, Employees, eLearning, Task Checklists (Cybrosys), and Utilities.

Credentials are personal — each user authenticates with their own Odoo API key, stored securely in the OS keystore (macOS Keychain / Windows Credential Manager / Linux Secret Service). Keys are never written to disk.

---

## Skills

| Skill | What It Does |
|---|---|
| `odoo` | Full read/write access to MPM's Odoo instance. Triggers on: "in Odoo", "our products", "the knowledge base", "find a contact", "sales order", "opportunity", "project tasks", "helpdesk ticket", "purchase order", "stock", "inventory", "employee", "create a task", "update the ticket", "cancel quotation", "archive", "mark lost", "bulk update", "how many records", "stage id for", "lost reasons", "course", "training", "elearning", "lesson", "slide", "quiz", "enroll", "create project", "archive project", "milestone", "subtask", "add follower", "post a note", "task chatter", "create stage", "checklist", "archive task" |

---

## Tools Reference

| Module | Tools |
|---|---|
| **Credentials** | `setup_odoo_credentials`, `clear_odoo_credentials` |
| **Products** | `search_products`, `get_product`, `get_product_stock` |
| **Knowledge** | `search_knowledge_articles`, `get_knowledge_article`, `create_knowledge_article`, `update_knowledge_article` |
| **Knowledge Templates** | `search_knowledge_templates`, `get_knowledge_template`, `list_knowledge_template_categories` |
| **Contacts** | `search_contacts`, `get_contact`, `create_contact` |
| **Sales** | `search_sales_orders`, `get_sales_order`, `create_sales_order`, `cancel_sale_orders`, `cancel_and_archive_quotations` |
| **CRM** | `search_crm_leads`, `get_crm_lead`, `create_crm_lead`, `update_crm_lead`, `list_crm_stages`, `mark_crm_lead_lost`, `list_crm_lost_reasons` |
| **Project — Core** | `list_projects`, `get_project`, `search_tasks`, `get_task`, `create_task`, `update_task`, `list_task_stages` |
| **Project — CRUD** | `create_project` *(supports `parent_id` for sub-projects)*, `update_project`, `archive_project` |
| **Project — Milestones** | `list_milestones`, `create_milestone`, `update_milestone` |
| **Project — Task Chatter** | `post_task_message`, `get_task_messages` |
| **Project — Subtasks** | `get_task_subtasks`, `create_subtask` |
| **Project — Lifecycle** | `archive_task` |
| **Project — Followers** | `add_task_follower`, `remove_task_follower` |
| **Project — Stages** | `create_task_stage`, `update_task_stage` |
| **Project — Drive Link** | `link_drive_document_to_project` |
| **Project — Checklists** | `list_checklist_templates`, `get_task_checklists`, `add_checklist_to_task`, `update_checklist_item` |
| **Helpdesk** | `search_helpdesk_tickets`, `get_helpdesk_ticket`, `create_helpdesk_ticket`, `update_helpdesk_ticket`, `list_helpdesk_teams` |
| **Purchase** | `search_purchase_orders`, `get_purchase_order` |
| **Inventory** | `search_inventory`, `get_stock_moves`, `list_internal_locations` |
| **Employees** | `search_employees`, `get_employee`, `list_departments` |
| **eLearning — Courses** | `search_courses`, `get_course`, `create_course`, `update_course`, `publish_course` |
| **eLearning — Slides** | `list_course_slides`, `get_slide`, `create_slide`, `update_slide`, `publish_slide`, `reorder_slides` |
| **eLearning — Quiz** | `get_quiz_questions`, `add_quiz_question`, `generate_quiz` |
| **eLearning — Enrollment** | `get_course_enrollment`, `enroll_in_course`, `bulk_enroll`, `send_course_invitation` |
| **eLearning — Media** | `set_course_cover`, `set_slide_cover`, `link_drive_document`, `add_course_resource` |
| **Utilities** | `odoo_search`, `odoo_get_record`, `odoo_search_read`, `get_record_count`, `bulk_update_records`, `archive_records`, `get_stage_ids`, `call_odoo_method` |

### Task Checklists (Cybrosys `projects_task_checklists` v19.0.1.0.0)
Models: `task.checklist` (templates), `checklist.item` (template items), `checklist.item.line` (per-task instances).
State values: `todo` / `in_progress` / `done` / `cancel` — no `is_done` field.
`update_checklist_item` uses Odoo action methods so task progress % and chatter update automatically.
Primary use case: phase acceptance criteria on Odoo Implementation project tasks.

### Project — Drive Link
`link_drive_document_to_project` attaches a Google Drive URL to a `project.project` record as an `ir.attachment` (type=url). Appears in the project's Attachments panel.

### Projects Module (v0.4.1 / v0.4.0)
`create_project` now accepts `parent_id` (int) to create sub-projects within a programme hierarchy.

---

## Setup Instructions

Full install guide: [MPM Odoo Plugin — Install Guide](https://docs.google.com/document/d/1t0J_r6IT3OsK5W4hdklizshxmZ_yb4S7mNnRouud4BYxA/edit)

**Quick summary:**

1. **Install the plugin** — Claude Desktop: Settings → Plugins → Add Plugin → paste `https://git.mpm.to/mpm/odoo-mpm-plugin`. Or double-click the `.plugin` file from the [CW-003 Drive folder](https://drive.google.com/drive/folders/1RYRUFKAltyp9nxcz203_TSD8eAABcuw5).
2. **Verify `uv` is installed** — Run `which uv` in terminal. If missing — Mac/Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`.
3. **Restart Claude Desktop** — Quit and relaunch.
4. **Generate a personal Odoo API key** — Odoo → Avatar → My Profile → Account Security → API Keys → New API Key → set expiration to **No Limit**.
5. **Connect** — In CoWork, type "Set up my Odoo credentials".
6. **Verify** — Ask Claude: "List my Odoo projects".

---

## Connection Details

| Field | Value |
|---|---|
| Instance | mpmedia.odoo.com |
| Database | mpmedia-odoo-sh-main-13285275 |
| Transport | stdio via `uv` |
| Auth | Personal API key in OS keystore (`odoo-mpm` service) |
| MCP server name | `odoo-mpm` |

---

## Changelog

### v0.4.1 (2026-05-29)
- `create_project` now accepts `parent_id` for sub-project hierarchy
- New tool: `link_drive_document_to_project` — attach Drive URL to project.project as ir.attachment
- New Cybrosys checklist tools (4): `list_checklist_templates`, `get_task_checklists`, `add_checklist_to_task`, `update_checklist_item`
- Built against actual Cybrosys module source (task.checklist / checklist.item / checklist.item.line)
- 97 total tools

### v0.4.0 (2026-05-28)
- Full Projects module (15 new tools): `create_project`, `update_project`, `archive_project`, `list_milestones`, `create_milestone`, `update_milestone`, `post_task_message`, `get_task_messages`, `get_task_subtasks`, `create_subtask`, `archive_task`, `add_task_follower`, `remove_task_follower`, `create_task_stage`, `update_task_stage`
- SKILL.md description trimmed to ≤100 words (plugin validator hard limit — documented)
- 92 total tools

### v0.3.0 (2026-05-28)
- eLearning module (22 new tools): Courses, Slides, Quiz, Enrollment, Media

### v0.2.0 (2026-05-28)
- Sales cancellation safety guard, bulk utilities, CRM lost reasons, Knowledge Templates

### v0.1.3 (2026-05-18)
- Knowledge article icon support

### v0.1.2 (2026-05-05)
- Initial CoWork registration

---

## Requirements

- [uv](https://github.com/astral-sh/uv) — Python package and environment manager
- `mcp[cli]` — installed automatically by uv on first run
- `keyring` — installed automatically by uv on first run

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| MCP server won't start | Confirm `uv` is installed: `which uv` |
| "Credentials not configured" | Run `setup_odoo_credentials` |
| Authentication failed | Rotate Odoo API key; run `clear_odoo_credentials` then `setup_odoo_credentials` |
| Keychain prompt on first use | Normal — allow it |
| `cancel_sale_orders` refused | Check order state — only `draft`/`sent` allowed |
| Plugin validation failed | Check SKILL.md description word count — must be ≤100 words |