What is MCP?

Model Context Protocol (MCP) is an open standard by Anthropic that lets AI assistants securely access external tools and data sources. This module implements an MCP server directly in Odoo.

Requirements

• Python: 3.10+
• Odoo: 18.0
• Dependencies: See requirements.txt

Quick Start

odoo-bin -d your_db -i llm_mcp_server

{
  "mcpServers": {
    "odoo-llm-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8069/mcp",
               "--header", "Authorization: Bearer YOUR_API_KEY"],
      "env": { "MCP_TRANSPORT": "streamable-http" }
    }
  }
}

claude mcp add-json odoo-llm-mcp-server '{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "mcp-remote", "http://localhost:8069/mcp",
           "--header", "Authorization: Bearer YOUR_API_KEY"],
  "env": {"MCP_TRANSPORT": "streamable-http"}
}'

experimental_use_rmcp_client = true

[mcp_servers.odoo-llm-mcp-server]
url = "http://localhost:8069/mcp"
http_headers.Authorization = "Bearer YOUR_API_KEY"

Architecture

┌─────────────┐   streamable-http   ┌──────────────┐      ┌─────────────┐
│ MCP Client  │ ←─────────────────→ │ Odoo MCP     │ ───→ │ llm.tool    │
│ (Claude)    │   JSON-RPC 2.0      │ Controller   │      │ Registry    │
└─────────────┘                     └──────────────┘      └─────────────┘

• Protocol: MCP 2025-06-18 spec via JSON-RPC 2.0
• Transport: streamable-http (HTTP with streaming responses)
• Endpoint: /mcp (POST for requests, streaming responses)
• Auth: Bearer token (Odoo API keys)
• Tools: Auto-discovered from llm.tool registry

API Reference

// Request
{"jsonrpc": "2.0", "id": 1, "method": "initialize",
 "params": {"protocolVersion": "2025-06-18", "capabilities": {}}}

// Response
{"jsonrpc": "2.0", "id": 1,
 "result": {"protocolVersion": "2025-06-18",
            "capabilities": {"tools": {}},
            "serverInfo": {"name": "odoo-mcp-server", "version": "1.0.0"}}}

// Request
{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}

// Response
{"jsonrpc": "2.0", "id": 2,
 "result": {"tools": [
   {"name": "search_records",
    "description": "Search for records in any Odoo model",
    "inputSchema": {"type": "object", "properties": {...}}}
 ]}}

// Request
{"jsonrpc": "2.0", "id": 3, "method": "tools/call",
 "params": {"name": "search_records",
            "arguments": {"model": "res.partner", "domain": []}}}

// Response
{"jsonrpc": "2.0", "id": 3,
 "result": {"content": [{"type": "text", "text": "..."}]}}

Creating Tools

Tools are auto-discovered from the llm.tool model. See llm_tool module for creating custom tools.

Testing & Debugging

MCP Inspector: https://modelcontextprotocol.io/docs/tools/inspector

Test your server:

• Verify connectivity
• Browse available tools
• Test tool execution
• Debug authentication issues

Odoo Logs: Check server logs for MCP-related errors

# Enable debug mode
odoo-bin --log-level=debug

Troubleshooting

No tools showing up?

• Check that tools are active in Odoo (LLM → Tools)
• Verify API key has access to tools
• Check user permissions

Authentication failed?

• Verify API key is correct
• Check key hasn't expired
• Ensure Bearer token format: Authorization: Bearer YOUR_KEY

Connection refused?

• Verify Odoo is running on specified port
• Check firewall settings
• For remote access, ensure Odoo is accessible from client

Tools failing to execute?

• Check Odoo logs for errors
• Verify user has required permissions
• Test tool manually in Odoo UI first

Security

• User-scoped: Each API key executes with that user's permissions
• ACL enforced: All Odoo access control rules apply
• No shared state: Each request is isolated
• Audit trail: All tool calls logged in Odoo

Roadmap

Future enhancements planned:

• MCP Resources - Expose Odoo records and documents as MCP resources for context injection
• MCP Prompts - Pre-built prompts for common Odoo workflows (sales, inventory, accounting)
• MCP Utilities - Additional MCP features like sampling and logging support

Contributions and feature requests welcome!

Resources

• MCP Protocol Spec
• Odoo LLM Repository
• Video Tutorial