odoo-timesheet-mcp

Odoo Timesheet MCP Server

An MCP (Model Context Protocol) server for managing Odoo 16 timesheets via the External API.

Features

• List timesheet entries with filtering
• Read detailed timesheet information
• Create new timesheet entries
• Update existing timesheet entries
• Delete timesheet entries

Prerequisites

• Node.js 18 or higher
• An Odoo 16 instance with External API access
• Odoo API credentials (username/password or API key)

Installation

npm install
npm run build

Configuration

Copy the example configuration file:

cp config.example.json config.json

Edit config.json with your Odoo instance details:

{
  "odoo_url": "https://your-instance.odoo.com",
  "odoo_db": "your-database-name",
  "odoo_username": "your-username",
  "odoo_password": "your-password-or-api-key"
}

Usage

As MCP Server

Add to your MCP client configuration:

{
  "mcpServers": {
    "odoo-timesheet": {
      "command": "node",
      "args": ["/path/to/odoo-timesheet-mcp/dist/index.js"],
      "env": {
        "ODOO_URL": "https://your-instance.odoo.com",
        "ODOO_DB": "your-database",
        "ODOO_USERNAME": "your-username",
        "ODOO_PASSWORD": "your-password"
      }
    }
  }
}

Available Tools

list_timesheets

List timesheet entries with optional filters.

Parameters:

• limit (optional): Maximum number of entries to return
• offset (optional): Number of entries to skip
• employee_id (optional): Filter by employee ID
• project_id (optional): Filter by project ID
• date_from (optional): Filter entries from date (YYYY-MM-DD)
• date_to (optional): Filter entries to date (YYYY-MM-DD)

read_timesheet

Read detailed information for specific timesheet entries.

Parameters:

• ids: Array of timesheet entry IDs to read

create_timesheet

Create a new timesheet entry.

Parameters:

• project_id: Project ID
• task_id (optional): Task ID
• name: Description of work
• unit_amount: Hours worked
• date: Date (YYYY-MM-DD)
• employee_id (optional): Employee ID

update_timesheet

Update existing timesheet entries.

Parameters:

• ids: Array of timesheet entry IDs to update
• values: Object with fields to update

delete_timesheet

Delete timesheet entries.

Parameters:

• ids: Array of timesheet entry IDs to delete

Development

npm run watch  # Watch mode for development
npm run dev    # Build and run

API Reference

This server uses the Odoo 16 External API (XML-RPC): https://www.odoo.com/documentation/16.0/developer/reference/external_api.html

The main model used is account.analytic.line which represents timesheet entries in Odoo.