How ivnvxd/mcp-server-odoo works
Project type and purpose
• This is a self-contained Python full-stack “MCP Server” that exposes Odoo ERP functionality over a Model Context Protocol interface. It’s essentially a microservice: a CLI/HTTP-like server that connects to an external Odoo instance, enforces access control, performs searches and CRUD operations, formats results for LLMs, and returns them to the calling AI assistant or client.
File structure
• Top-level:
• mcp_server_odoo/ ← core service package
• pyproject.toml ← build/config
• .github/ci workflows
• tests/ ← unit and integration tests
• Inside mcp_server_odoo:
• __main__.py & server.py ← entrypoint and server loop
• config.py & logging_config.py ← environment & logging setup
• access_control.py ← API key / user‐pass auth
• odoo_connection.py ← XMLRPC/HTTP connectivity to Odoo
• resources.py & uri_schema.py ← URI parsing & resource dispatch
• formatters.py ← LLM-optimized output formatting
• error_handling.py ← exception mapping & responses
• performance.py & tools.py ← caching, throttling, utility functions
README for additional insights
• The README confirms a CLI command (“uvx mcp-server-odoo”) that spawns a service listening for MCP requests.
• It lists the high-level tools (search_records, get_record, etc.) and the required environment variables (ODOO_URL, ODOO_API_KEY, etc.).
Main components & their interactions
a. Client / AI assistant
• Initiates requests via the MCP protocol (JSON-RPC or CLI pipes).
b. CLI / Server entrypoint
• __main__.py → server.py: boots the server, reads env vars (config), sets up logging.
c. Access control module
• Validates API key or username/password against Odoo rules.
d. URI Schema & Router
• Parses incoming “odoo://…” URIs or JSON payloads, dispatches to resources.
e. Resource Handlers
• resources.py: implements search, get, create, update, delete operations.
f. Odoo Connection
• odoo_connection.py: manages HTTP/XMLRPC calls to external Odoo instance, handles sessions.
g. Formatting & Response
• formatters.py: post-processes raw Odoo JSON/XML data into hierarchical text for LLMs.
h. Error Handling
• error_handling.py: catches exceptions, maps to MCP error codes/messages.
i. Performance & Utilities
• performance.py: caching, pagination logic
• tools.py: shared helpers
j. External System
• Odoo ERP instance with installed MCP module.
Flow summary:
Client → Entrypoint → AccessControl → Router/URI Schema → Resource Handler → Odoo Connection → Odoo ERP
← Raw data ← Formatting ← ErrorHandling → Response → Client
Architectural patterns & design principles
• Modularity: each concern (config, auth, routing, connection, formatting, error handling) is in its own module.
• Layered architecture: transport (CLI/MCP) → authentication → routing → business logic → external system.
• Dependency injection via environment variables (config.py).
• Single responsibility: resources.py only implements high-level operations, odoo_connection.py only manages RPC plumbing.
• Test coverage: conftest and tests ensure each layer is isolated and mockable.