Odoo MCP Server

An MCP (Model Context Protocol) server that connects AI agents in Cursor to your Odoo instance. Tell your AI to "turn this PRD into tasks in Odoo" and it will create a full hierarchy of epics, tasks, and subtasks with tags, priorities, and assignments.

No cloning required — just configure and go.

Quick Start

1. Install uv

uv is a fast Python package manager that includes uvx for running tools directly from git repos.

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Get Your Odoo API Key

1. Log into your Odoo instance
2. Go to My Profile (click your avatar → My Profile)
3. Navigate to Preferences → Account Security
4. Click New API Key, name it "Cursor MCP", and copy the key

3. Configure Cursor

Create or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "odoo": {
      "command": "/Users/YOUR_USERNAME/.local/bin/uvx",
      "args": [
        "--from",
        "git+https://github.com/willy5xx/odoo_mcp.git",
        "odoo-mcp"
      ],
      "env": {
        "ODOO_URL": "https://your-instance.odoo.com",
        "ODOO_DB": "your-database-name",
        "ODOO_USERNAME": "your-email@example.com",
        "ODOO_API_KEY": "your-api-key"
      }
    }
  }
}

Replace the placeholder values:

• YOUR_USERNAME — your macOS username (run whoami to check)
• ODOO_URL — your Odoo instance URL (e.g., https://mycompany.odoo.com)
• ODOO_DB — your database name (often the subdomain, e.g., mycompany)
• ODOO_USERNAME — your Odoo login email
• ODOO_API_KEY — the API key you created in step 2

4. Restart Cursor

Quit and reopen Cursor for the MCP server to load.

6. Test It

In Cursor, ask your AI:

• "Test the Odoo connection"
• "List my Odoo projects"

If it works, you're all set!

---

Important Notes

Issue	Solution
uvx not found	Cursor can't find uvx via PATH. Always use the full absolute path: /Users/YOUR_USERNAME/.local/bin/uvx
SSL certificate errors	Usually handled automatically. If you're behind a corporate proxy, see Troubleshooting
ODOO_URL format	Use the base URL only (e.g., https://mycompany.odoo.com). Do NOT include /odoo or other paths
Changes not taking effect	Restart Cursor after editing ~/.cursor/mcp.json

---

Usage Examples

Once configured, you can use natural language to manage Odoo:

"List my Odoo projects"

"Read @specs/feature-prd.md and create tasks in the 'Mobile App' project. 
 Break it into epics with subtasks, tag by feature area, and set priorities."

"Show me tasks in the Backend project and update the auth task to urgent priority"

"Create a new task in the API project: implement rate limiting for the /users endpoint"

"Add a subtask to task #123: write unit tests for the validation logic"

---

Available Tools

Tool	Description
odoo_test_connection	Verify credentials and connectivity
odoo_list_projects	List all projects with metadata
odoo_create_project	Create a new project
odoo_update_project	Update project fields (name, manager, active status)
odoo_get_project_stages	Get kanban stages for a project
odoo_create_task	Create a single task (supports subtasks via parent_id)
odoo_create_tasks_batch	Create multiple tasks at once
odoo_list_tasks	List tasks in a project
odoo_update_task	Update any field on an existing task
odoo_post_task_message	Post progress updates to task chatter
odoo_search_users	Find users by name/email for assignment
odoo_list_tags	List existing project tags
odoo_create_milestone	Create project milestones
odoo_list_milestones	List milestones in a project
odoo_search_records	Generic search on any Odoo model
odoo_create_record	Generic create on any Odoo model
odoo_update_record	Generic update for any Odoo model
odoo_delete_record	Generic delete for any Odoo model

---

How PRD → Tasks Works

When you ask your AI to turn a PRD into Odoo tasks:

1. AI reads the PRD from a file or pasted text
2. Calls odoo_list_projects to find the target project
3. Calls odoo_get_project_stages to understand the workflow
4. Decomposes the PRD into a task hierarchy:
   • Top-level tasks = epics / feature areas
   • Subtasks = individual work items
5. Creates epics via odoo_create_task, getting back IDs
6. Creates subtasks via odoo_create_tasks_batch with parent_id linking
7. Tags are auto-created if they don't exist

---

Supported Odoo Versions

Works with any Odoo version that supports XML-RPC (12.0+):

• Odoo Community
• Odoo Enterprise
• Odoo.sh
• Odoo Online (SaaS)

---

Troubleshooting

Connection fails

1. Verify your credentials by logging into Odoo manually
2. Check that your API key is valid (regenerate if needed)
3. Ensure ODOO_URL doesn't have a trailing slash or /odoo path
4. Verify the database name matches exactly

SSL errors

SSL certificates are handled automatically via the bundled certifi package. If you're behind a corporate proxy or firewall that intercepts SSL, add these environment variables to your config:

"env": {
  "ODOO_URL": "...",
  "ODOO_DB": "...",
  "ODOO_USERNAME": "...",
  "ODOO_API_KEY": "...",
  "SSL_CERT_FILE": "/path/to/your/corporate-ca-bundle.pem",
  "REQUESTS_CA_BUNDLE": "/path/to/your/corporate-ca-bundle.pem"
}

To find your system's certificate bundle:

python3 -c "import certifi; print(certifi.where())"

uvx errors

Verify uvx is installed and get the correct path:

which uvx

Use that exact path in your config.

---

Environment Variables

Variable	Required	Description
ODOO_URL	Yes	Your Odoo instance URL (base URL only)
ODOO_DB	Yes	Database name
ODOO_USERNAME	Yes	Login email
ODOO_API_KEY	Yes	API key (not password)
SSL_CERT_FILE	No	Path to CA certificate bundle (only for corporate proxies)
REQUESTS_CA_BUNDLE	No	Path to CA certificate bundle (only for corporate proxies)
LOG_LEVEL	No	DEBUG, INFO (default), WARNING, ERROR

---

License

MIT