odoo-mpm-plugin/README.md

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.0 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 12 modules: Products, Knowledge (with Templates), Contacts, Sales, CRM, Project (full CRUD + milestones + subtasks + chatter + followers + stages), Helpdesk, Purchase, Inventory, Employees, eLearning, 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", "what stage is", "create a task", "update the ticket", "cancel quotation", "cancel quote", "archive", "mark lost", "bulk update", "how many records", "count of", "stage id for", "resolve stage", "search with filters", "filter by", "lost reasons", "course", "training", "elearning", "lesson", "slide", "quiz", "enroll", "enrollment", "publish course", "create course", "add lesson"

---

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, 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
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

Knowledge Article Icon Support

create_knowledge_article, update_knowledge_article, and get_knowledge_article all support an icon parameter — a Unicode emoji (e.g. "⚙️", "🔌", "🖥️") that sets the article's icon in the KB tree. Browse emojis at: https://emojipedia.org

Projects Module (v0.4.0)

15 new tools completing full project lifecycle management.

Project CRUD: Create projects with configurable visibility (employees / portal / followers), update metadata, archive/restore.

Milestones: Full CRUD on project.milestone. update_milestone(is_reached=True) marks complete; list_milestones filters to open by default.

Task chatter: post_task_message posts comments or internal notes to a task's chatter thread (comment vs internal message_type). get_task_messages returns the full message history.

Subtasks: get_task_subtasks returns all direct children of a task. create_subtask links a new task to a parent and inherits the parent's project if none specified.

Followers: add_task_follower / remove_task_follower accept either partner_ids or user_ids — user IDs are resolved to partner IDs automatically before calling message_subscribe / message_unsubscribe.

Stage management: create_task_stage creates a kanban column and links it to one or more projects. update_task_stage supports incremental add_project_ids / remove_project_ids without replacing the full association list.

---

eLearning Module (v0.3.0)

22 tools across 5 groups for building and managing internal, reseller, and end-client courses.

Slide types: pdf (Drive link), youtube_video, vimeo_video, infographic, webpage (native HTML article)

Google Drive policy: All image and document operations use the Google Workspace MCP connector when available. The skill never asks the user to construct or copy Drive URLs unless the connector is absent.

Audience tiers via course settings:

• Internal employees: visibility=members, enroll=invite, enroll_group_names=['Internal Users']
• Resellers: visibility=connected, enroll=public
• End-clients: visibility=public, enroll=public

Onboarding hook: enroll_in_course and bulk_enroll are designed to be called by the project management plugin to automatically enroll new customers in courses on contract/onboarding events.

Quiz generation: Read course content → Claude generates questions → call generate_quiz to write all at once.

Sales Cancellation Safety Guard

cancel_sale_orders and cancel_and_archive_quotations only operate on orders in Quotation (draft) or Quotation Sent (sent) state. Both tools pre-validate all IDs and raise a named error listing any orders in other states before touching anything. Confirmed Sale Orders cannot be cancelled via Claude.

Utility Tools (v0.2.0)

• odoo_search_read — preferred for efficient queries: full domain filter + return only specified fields. Avoids token bloat vs. odoo_get_record.
• get_record_count — count matching records without fetching data. Use before bulk operations.
• bulk_update_records — set one or more fields on a list of IDs in a single API call. Works for stages, custom Studio fields (x_studio_*), status flags.
• archive_records — soft-delete via active=False. For sale.order, cancel first.
• get_stage_ids — resolve stage names to IDs with case-insensitive exact matching across crm.stage, project.task.type, helpdesk.stage.
• call_odoo_method — escape hatch for any model method not covered by other tools.

---

Setup Instructions

Full install guide: MPM Odoo Plugin — Install Guide

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.
2. Verify uv is installed — Run which uv in terminal. If missing — Mac/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh. Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex".
3. Restart Claude Desktop — Quit and relaunch. uv auto-installs Python dependencies (keyring) on first start.
4. Generate a personal Odoo API key — Odoo → Avatar → My Profile → Account Security → API Keys → New API Key → set expiration to No Limit. Copy immediately — not shown again.
5. Connect — In CoWork, type "Set up my Odoo credentials". Claude will prompt for your Odoo login email and API key.
6. Verify — Ask Claude: "List my Odoo projects". A project list confirms full connectivity.

Setup Checklist

• Plugin installed (URL or .plugin file)
• uv installed and in terminal PATH
• Claude restarted after install
• Odoo API key generated (No Limit expiration)
• setup_odoo_credentials completed
• "List my Odoo projects" returns data

---

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

---

Workflow Notes

• Before updating a task or ticket stage, call list_task_stages or get_stage_ids to confirm valid stage IDs.
• Use odoo_search_read for any query where you only need specific fields — more efficient than odoo_get_record.
• Knowledge article bodies are HTML — use basic HTML formatting when creating or updating.
• Before calling mark_crm_lead_lost, call list_crm_lost_reasons to show the user available reasons.
• Before calling cancel_sale_orders, verify orders are in draft or sent state — the tool will reject anything else with a clear error.

---

Requirements

• 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