内容
# Odoo MCP 服务器
一个遵循[模型上下文协议](https://modelcontextprotocol.io)（MCP）的服务器，允许Claude等AI助手安全地与Odoo 18 ERP实例交互 —— 具备**每个用户 OAuth 2.1 身份**、**员工自助服务**工作流程、通用记录CRUD和可选的文档签名。
## 为什么使用这个服务器？
已经存在多个Odoo MCP服务器（Odoo自己的`mcp_server`插件、MuK MCP和社区XML-RPC桥接器，如`ivnvxd/mcp-server-odoo`）。它们大多是**通用CRUD桥接器，使用单个共享管理员凭证**。
这个服务器不同 —— 它围绕**经过身份验证的最终用户**构建：
- **OAuth 2.1 + PKCE**，带有每个请求的承载令牌；每个请求都映射到调用用户的Odoo员工记录。
- **员工自助服务工具** —— 您自己的个人资料、经理、团队、请假余额/申请、公共假期和人力资源文档 —— 所有这些都自动限定为已验证用户，从不针对任意记录。
- **粒度OAuth范围**，每个工具（`odoo.read`、`odoo.hr.profile`、`odoo.leave.write`等），而不是全有或全无的访问权限。
- 通用**CRUD工具**仍然可用于管理员/集成范围。
如果您想要一个面向每个用户、专注于人力资源、优先进行身份验证的服务器，那么这就是为您准备的。如果您只需要一个具有管理员凭证的CRUD桥接器，那么上述社区服务器更简单。
## 功能
- **OAuth 2.1 / PKCE**身份验证（Google作为开箱即用的身份提供商；通过`OAUTH_PROVIDER=custom`可插拔）。
- **30个MCP工具**：7个通用CRUD、16个员工自助服务、7个可选签名。
- **两种传输方式**：可流式HTTP（远程MCP）和stdio（本地客户端）。
- **每个用户范围**：员工身份从OAuth令牌中派生，而非从工具输入。
- **可为任何Odoo配置**：自定义员工字段、文档文件夹和可选签名模块都可以通过环境变量选择加入。
- **生产就绪**：Docker镜像、CI和参考Cloud Run部署。
## 快速入门
### 先决条件
- Python 3.12+
- Odoo 18实例和API密钥（或用户名/密码）
- Google OAuth客户端（用于生产身份验证）—— 或在本地运行`OAUTH_DEV_MODE=true`
### 安装
```bash
git clone https://github.com/OWNER/odoo-mcp-server.git
cd odoo-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```
### 配置
复制`.env.example`到`.env`并填写您的值。启动所需的最低配置：
```bash
ODOO_URL=https://your-odoo-instance.example.com
ODOO_DB=your-database-name
ODOO_API_KEY=your_api_key_here
# OAuth（生产环境）。对于本地开发，您可以设置OAUTH_DEV_MODE=true。
OAUTH_PROVIDER=google
OAUTH_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
OAUTH_CLIENT_SECRET=your_client_secret_here
OAUTH_RESOURCE_IDENTIFIER=https://your-mcp-server.example.com
OAUTH_REDIRECT_URI=https://your-mcp-server.example.com/oauth/callback
```
启动时验证必需设置 —— 如果缺少任何设置，服务器会**快速失败**并显示清晰的消息（无静默默认值）。
### 运行服务器
```bash
# HTTP服务器（远程MCP / Claude.ai连接器）
python -m odoo_mcp_server.http_server
# stdio（本地MCP客户端，如Claude Desktop）
python -m odoo_mcp_server.server
```
## 可用工具
### 通用CRUD（范围：`odoo.read` / `odoo.write`）
| 工具 | 描述 |
|------|-------------|
| `search_records` | 使用域过滤器搜索记录 |
| `get_record` | 按ID获取单个记录 |
| `create_record` | 创建新记录 |
| `update_record` | 更新现有记录 |
| `delete_record` | 删除记录 |
| `count_records` | 统计匹配域的记录 |
| `list_models` | 列出可用的Odoo模型 |
### 员工自助服务（人力资源/请假/文档范围）
个人资料和组织：`get_my_profile`、`get_my_manager`、`get_my_team`、`find_colleague`、`get_direct_reports`、`update_my_contact`。
请假：`get_my_leave_balance`、`get_my_leave_requests`、`request_leave`、`cancel_leave_request`、`get_public_holidays`。
文档：`get_my_documents`、`get_document_categories`、`upload_identity_document`、`download_document`、`get_document_details`。
所有这些都自动限制在已验证用户的自己的数据范围内。
### 文档签名 —— 可选（范围：`odoo.sign.*`）
默认禁用。需要社区**OCA `sign_oca`**插件（`sign.oca.*`模型，而非Odoo企业签名）。启用`SIGN_MODULE_ENABLED=true`以公开：`get_my_pending_signatures`、`get_my_signature_requests`、`get_signature_request_status`、`list_sign_templates`、`send_signature_request`、`download_signed_document`、`cancel_signature_request`。
## 可选功能
这些功能默认为Odoo安全值，因此服务器无需额外配置即可在普通Odoo上运行。
| 设置 | 目的 |
|---------|---------|
| `ENABLED_TOOL_GROUPS` | 以逗号分隔的工具组，暴露给：`crud`、`employee`（默认`crud,employee`）。使用`crud`作为通用管理员桥接器，或使用`employee`仅限自助服务。 |
| `EMPLOYEE_CUSTOM_FIELDS` | 输出键的JSON映射 → 自定义`hr.employee`字段，例如`{"preferred_name":"x_preferred_name","division":"x_division"}`。在`get_my_profile`上显示。 |
| `DMS_ALLOWED_FOLDERS` / `DMS_RESTRICTED_FOLDERS` | 员工可以查看的文档文件夹名称，以逗号分隔， vs. 必须看不到的。 |
| `SIGN_MODULE_ENABLED` | 暴露OCA签名工具（需要`sign_oca`插件）。 |
| `INTERNAL_EMAIL_DOMAIN` | 电子邮件匹配此域的用户将获得扩展的写入范围。 |
| `YOLO_MODE` | `read` = 无身份验证只读（仅暴露读取工具）；`true` = 无身份验证完全访问。仅限受信任/本地使用。 |
### 部署模式
服务器可以在单个受信任网络的Odoo实例上运行，无需身份验证，也可以部署为多用户、多环境的OAuth。参见 **[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)** 获取复制粘贴配方（无身份验证/只读、单个身份API密钥、Google OAuth、自定义OIDC、stdio）和如何选择工具组。
## Claude Desktop集成
```json
{
"mcpServers": {
"odoo": {
"url": "https://your-deployment-url/mcp",
"transport": "streamable-http"
}
}
}
```
参见 [docs/CLAUDE_INTEGRATION.md](docs/CLAUDE_INTEGRATION.md) 了解完整的Claude.ai连接器设置（Google OAuth重定向URI、范围等）。
## 测试
```bash
pytest tests/unit # 快速，无外部服务
pytest tests/integration # 需要真实的Odoo（跳过无凭证）
pytest --cov=src/ --cov-report=html
```
单元测试开箱即用 —— `conftest.py`提供了占位符Odoo设置，因此无需任何外部依赖。
## 部署
### Docker
```bash
docker build -t odoo-mcp-server -f docker/Dockerfile .
docker run -p 8080:8080 \
-e ODOO_URL=https://your-odoo-instance.example.com \
-e ODOO_DB=your-database-name \
-e ODOO_API_KEY=your_key \
odoo-mcp-server
```
### Google Cloud Run
参考Cloud Run部署已配置在`.github/workflows/ci.yml`中。设置`GCP_REGION`存储库变量和[docs/CI_CD.md](docs/CI_CD.md)中列出的机密，然后合并到`main`分支。
## 项目结构
```
odoo-mcp-server/
├── src/odoo_mcp_server/
│ ├── server.py # stdio MCP入口点
│ ├── http_server.py # HTTP传输 + OAuth流程
│ ├── config.py # 设置、范围、速率限制
│ ├── oauth/ # OAuth 2.1资源服务器，令牌验证
│ ├── odoo/ # Odoo XML-RPC客户端
│ ├── tools/ # MCP工具（记录、员工、签名）
│ └── resources/ # MCP资源（模型发现）
├── tests/ # 单元测试/集成测试/e2e
├── docker/ # Docker配置
├── terraform/ # 可选AI/安全审查员基础设施
└── docs/ # 安全、CI/CD、Claude集成
```
## 安全
- 所有身份验证流程均使用OAuth 2.1和PKCE
- 针对提供商的JWKS进行JWT验证
- 员工身份从令牌中派生，而非从用户输入
- 所有员工查询都限制在已验证用户范围内
- 凭证仅从环境加载 —— 绝不硬编码
通过[SECURITY.md](SECURITY.md)报告漏洞。有关安全模型，请参见[docs/SECURITY.md](docs/SECURITY.md)。
## 贡献
欢迎贡献 —— 请参见[CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
[MIT](LICENSE)
