Panda Odoo MCP Server

Developed by

This module was developed by Paolo Nugnes and TechLab.

TechLab is a company specialized in custom software development and enterprise system integration. Visit our website www.techlab.it for more information about our services.

Overview

The Odoo MCP Server is a standardized interface for interacting with Odoo instances through the MCP (Model Context Protocol). It provides support for:

• Communication Protocols:

  • stdio: Direct communication via stdin/stdout

  • streamable_http: HTTP communication with streaming response support

• Resource Management:

  • Odoo records (single and list)

  • Binary fields

  • Real-time updates

• Tools:

  • Search and read records

  • Create and update records

  • Delete records

  • Call custom methods

• Security:

  • Authentication and session management

  • Rate limiting

  • CORS for streamable_http connections

System Requirements

Hardware Requirements

• CPU: 2+ cores

• RAM: 4GB minimum (8GB recommended)

• Disk Space: 1GB minimum

Software Requirements

• Python 3.9+

• Odoo 15.0+

  • Required modules: base, web, bus

  • Database configured with admin user

• Docker (optional)

Network Requirements

• Port 8069 (Odoo)

• Port 8080 (streamable_http, optional)

• Port 5432 (PostgreSQL, if local)

Security Requirements

• SSL certificate for HTTPS (production)

• Configured firewall

• VPN access (optional)

Installation

Direct Installation

Docker Installation

Configuration

The server can be configured through a JSON file. Several configuration templates are available:

• config.example.json: Main template to copy and modify

• config.dev.json: Development environment template (optional)

• config.prod.json: Production environment template (optional)

To get started:

Selecting the Connection Type

The Odoo MCP server supports several connection types, configurable via the connection_type field in config.json. Supported values:

• stdio: Default, direct communication via stdin/stdout

• streamable_http: HTTP with streaming/chunked responses (real-time data flows)

• http: Classic HTTP POST (stateless, single request/response)

Example configuration:

• Use streamable_http for real-time streaming over HTTP (endpoint: POST /mcp)

• Use http for classic REST requests (endpoint: POST /mcp)

• Use stdio for direct communication (default)

Example of complete configuration:

Configuration

You can configure the server via environment variables in your .env file or directly in docker-compose.yml.

Note: Environment variables (from .env or the container environment) always take precedence over values in config.json.

Main variables:

• ODOO_URL, ODOO_DB, ODOO_USER, ODOO_PASSWORD (Odoo connection)

• PROTOCOL, CONNECTION_TYPE, LOGGING_LEVEL (MCP server)

• REQUESTS_PER_MINUTE, SSE_QUEUE_MAXSIZE, ALLOWED_ORIGINS (advanced)

Example .env:

Starting the Server

The server can be started in two modes: stdio (default) and streamable_http. The configuration file is optional and, if not specified, the server will automatically look for the file in odoo_mcp/config/config.json.

stdio Mode (default)

streamable_http Mode

HTTP Modes

The Odoo MCP server supports two HTTP modes:

1. HTTP Streaming Chunked (streamable_http):

   • Endpoint: POST /mcp

   • Keeps the connection open and streams data

   • Ideal for real-time data flows

   • Required headers:

     Content-Type: application/json Connection: keep-alive

2. Classic HTTP POST (http):

   • Endpoint: POST /mcp

   • Handles a single request/response (stateless)

   • Standard REST behavior

   • Required headers:

     Content-Type: application/json

3. Server-Sent Events (SSE):

   • Endpoint: GET /sse

   • Server-push event support

   • Required headers:

     Accept: text/event-stream

To configure the HTTP mode, set connection_type in config.json:

Example Calls

1. HTTP Streaming Chunked:

2. Classic HTTP POST:

3. Server-Sent Events:

Server Verification

stdio Mode

streamable_http Mode

http Mode (Classic HTTP POST)

Server-Sent Events (SSE)

Usage

stdio Connection

streamable_http Connection

Connecting Claude Desktop to the Odoo MCP server (stdio)

To connect Claude Desktop to the Odoo MCP server using the stdio protocol:

1. Make sure the Odoo MCP server is installed and working.

2. Open Claude Desktop settings (Claude menu → Settings → Developer → Edit Config).

3. Add the following configuration to the mcpServers section of your claude_desktop_config.json file:

Replace C:/absolute/path/to/your/config.json with the actual path to your configuration file.

4. Save and restart Claude Desktop. You should see the MCP tools available.

Note: Claude Desktop only communicates via stdio. Do not use streamable_http for connecting with Claude Desktop.

Documentation

Complete documentation is available in the docs/ directory:

• mcp_protocol.md: MCP protocol documentation

• odoo_server.md: Odoo server documentation

• server_usage.md: Server usage guide

Contributing

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

License

This project is released under the MIT License. See the LICENSE file for details.

Update

Update from Source

Update with Docker

Uninstallation

Uninstall from Source

Uninstall with Docker

Advanced Configuration

Environment Configuration

Development

Production

Configuration Backup

Advanced Usage

Error Handling

Best Practices

1. Connection Management:

   async with Client() as client: await client.initialize() # Operations

2. Cache Management:

   # Cache configuration cache_config = { 'enabled': True, 'ttl': 300, 'max_size': 1000 }

3. Session Management:

   # Create session session = await client.create_session() # Validate session if await client.validate_session(session_id): # Operations

Troubleshooting

Common Issues

1. Connection Error:

   ERROR: Could not connect to Odoo server

   Solution:

   • Verify that Odoo is running on port 8069

   • Check that the firewall allows access to port 8069

   • Verify that the Odoo URL in the configuration file is correct

   • Check that the database is accessible

2. Authentication Error:

   ERROR: Authentication failed

   Solution:

   • Verify that username and api_key in the configuration file are correct

   • Check that the user has the necessary permissions in the Odoo database

   • Verify that the specified database exists

   • Check that the base, web, and bus modules are installed

3. Protocol Error:

   ERROR: Protocol error

   Solution:

   • Verify that the specified protocol (xmlrpc/jsonrpc) is supported

   • Check that the Odoo version is compatible (15.0+)

   • Verify that the connection type (stdio/streamable_http) is correct

   • Check the logs for specific error details

4. Rate Limiting Error:

   ERROR: Rate limit exceeded

   Solution:

   • Increase the requests_per_minute value in the configuration file

   • Implement a retry mechanism with backoff

   • Optimize requests to reduce the number of calls

5. Cache Error:

   ERROR: Cache error

   Solution:

   • Verify that the configured cache type is supported

   • Check that there is sufficient space for the cache

   • Temporarily disable the cache if necessary

Error Logs

Important note: In the current version, the Odoo MCP server can write logs to multiple destinations depending on configuration:

• If the logging section in config.json includes a StreamHandler, logs are written to the console (stderr).

• If a FileHandler is present, logs are also written to a file at the path specified by filename.

• If there is no logging, logs are written only to stderr (console).

Example:

• In this example, logs go both to the console and to the file server.log in the directory where you start the server.

• You can change the log file path by editing the filename field (e.g., "filename": "logs/dev.log" or an absolute path).

Support

For technical support:

1. Check the documentation

2. Open an issue

3. Contact support@techlab.it

Running with Docker

You can run the Odoo MCP Server in a Docker container using the provided Dockerfile and docker-compose.yml.

Quick Start

This will:

• Build the image from the Dockerfile.

• Start the MCP server on port 8080 (default).

• Persist logs in the ./logs directory.

Configuration

You can configure the server via environment variables in your .env file or directly in docker-compose.yml.

Main variables:

• ODOO_URL, ODOO_DB, ODOO_USER, ODOO_PASSWORD (Odoo connection)

• PROTOCOL, CONNECTION_TYPE, LOGGING_LEVEL (MCP server)

• REQUESTS_PER_MINUTE, SSE_QUEUE_MAXSIZE, ALLOWED_ORIGINS (advanced)

Example .env:

Custom Configuration File

You can mount your own config file:

Accessing the Server

• HTTP streaming: POST http://localhost:8080/mcp

• SSE: GET http://localhost:8080/sse

Stopping the Server