Metadata-Version: 2.4
Name: odooclaw-mcp
Version: 2.1.0
Summary: A modular, type-safe, and secure MCP server for interacting with Odoo 18 ORM
Author-email: Nicolás Ramos <nicolasramos@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://github.com/nicolasramos/odooclaw-mcp
Project-URL: Documentation, https://github.com/nicolasramos/odooclaw-mcp/blob/main/README.md
Project-URL: Repository, https://github.com/nicolasramos/odooclaw-mcp
Project-URL: Issues, https://github.com/nicolasramos/odooclaw-mcp/issues
Keywords: odoo,mcp,orm,api,server
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: fastmcp>=0.1.0
Requires-Dist: mcp-server>=0.1.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# OdooClaw MCP

Standalone MCP (Model Context Protocol) server for Odoo 18 over `stdio`.

**MCP name:** `io.github.nicolasramos/odoo-mcp`  
**PyPI package:** `odooclaw-mcp`  
**Official CLI:** `odooclaw-mcp`

Backward-compatible aliases are also installed:

- `odoo-mcp`
- `odoo-mcp-server`
- `odoo-18-mcp-server`

## Quick Start

### 1) Install

```bash
pip install odooclaw-mcp
```

From source:

```bash
git clone https://github.com/nicolasramos/odooclaw-mcp.git
cd odooclaw-mcp
pip install -e .
```

### 2) Configure environment

```bash
cp .env.example .env
```

Required:

```env
ODOO_URL=https://yourcompany.odoo.com
ODOO_DB=your_database
ODOO_USERNAME=your_username
ODOO_PASSWORD=your_password
```

Optional:

```env
ODOO_MCP_DEFAULT_LIMIT=50
ODOO_MCP_MAX_LIMIT=80
LOG_LEVEL=INFO
```

### 3) Validate and run

```bash
odooclaw-mcp --check-config
odooclaw-mcp
```

Alternative:

```bash
python -m odoo_mcp
```

## MCP Client Configuration (stdio)

```json
{
  "mcpServers": {
    "odoo": {
      "command": "odooclaw-mcp",
      "env": {
        "ODOO_URL": "https://yourcompany.odoo.com",
        "ODOO_DB": "your_database",
        "ODOO_USERNAME": "your_username",
        "ODOO_PASSWORD": "your_password",
        "ODOO_MCP_DEFAULT_LIMIT": "50",
        "ODOO_MCP_MAX_LIMIT": "80"
      }
    }
  }
}
```

## Scope

- 38+ MCP tools for Odoo operations (CRUD + business actions)
- Pydantic validation for all tool payloads
- Odoo 18 compatibility helpers (customer_rank / supplier_rank / payment_state)
- Security guards (model allowlist, denylisted fields, action guard, unlink blocked)
- Structured logging and audit actions

## Security Model

The server uses standard Odoo JSON-RPC endpoints and executes operations as the
configured Odoo session user.

For production, use a dedicated least-privilege Odoo account.

## Production Notes

- This is a `stdio` MCP server, not an HTTP API service.
- Docker/Compose support is mainly for packaging or controlled runtime scenarios.
- In normal usage, your MCP client launches the server process directly.
- Keep Odoo credentials in environment variables or a secrets manager.

## Known Limitations

- One Odoo credential context per MCP process.
- `ODOO_DB` is currently required by the authentication flow.
- Some tools require specific Odoo apps/modules (CRM, Helpdesk, Project, etc.).
- Designed for Odoo 18 field semantics.

## Development

```bash
pip install -e .[dev]
ruff check src tests
black --check src tests
mypy src --ignore-missing-imports
pytest tests -v
python -m build
twine check dist/*
```

## Docs

- [Architecture](docs/ARCHITECTURE.md)
- [Deployment](docs/DEPLOYMENT.md)
- [QA Runbook](docs/QA_RUNBOOK.md)

## License

MIT - see [LICENSE](LICENSE).
