Odoo Sh MCP Server

🚀 Odoo.sh MCP Server

An SSH-based Model Context Protocol server for Odoo.sh that enables building custom apps with AI assistance using Git workflow tools

✨ Features

Core Operations (v1.0)

• 🔐 SSH-Based Access: Establish a secure connection via SSH keys (no API token required).
• 🌿 Branch Operations: View branches, obtain the current branch, and access commit history.
• 🏗️ Build Management: Trigger builds, monitor their status, and view logs.
• 💾 Database Access: List PostgreSQL databases and their sizes.
• 💻 System Monitoring: Retrieve hostname, uptime, disk, memory, and version information.
• 🐍 Odoo Shell: Execute Python code within the Odoo environment.

🆕 Git Workflow & App Development (NEW in v1.0)

• 📁 File Management: Create, read, and update files using base64 encoding.
• 📂 Directory Operations: Create directory structures for modules.
• 📖 Git Status: Check modified, staged, and untracked files.
• ➕ Git Add: Stage files for commit (either single or multiple).
• ✅ Git Commit: Commit changes with custom messages.
• 🚀 Git Push: Push commits to the remote Odoo.sh repository.
• 🌿 Git Checkout: Switch branches or create new feature branches.
• 🔄 Git Pull: Sync changes from the remote repository.
• 🛠️ AI-Assisted Development: Leverage AI agents to build complete Odoo modules.

🚀 Quick Start

# 1. Install dependencies
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env and add your ODOO_SH_API_TOKEN

# 3. Build
npm run build

# 4. Add to your MCP client config (e.g., Claude Desktop)
# See Configuration section below

📦 Installation

Prerequisites

• Node.js >= 18.0.0
• npm (comes with Node.js)
• Odoo.sh Account with SSH access
• OpenSSH client installed (included in Windows 10+, macOS, Linux)
• MCP Client (Warp, Claude Desktop, Cline, Continue, etc.)

Steps

1. Clone or download this repository
2. Install dependencies:

   npm install
   

3. Set up SSH access:
   • Add your SSH public key to Odoo.sh (Settings → Collaborators → SSH Keys).
   • Obtain your build ID and hostname from Odoo.sh (format: BUILD_ID@project-name.dev.odoo.com).
   • Save your private key to a secure location.
4. Build the project:

   npm run build
   

🛠️ Configuration

Environment Variables

Create a .env file or set environment variables:

ODOO_SH_SSH_HOST=project-name.dev.odoo.com
ODOO_SH_SSH_USER=BUILD_ID              # e.g., 25357858
ODOO_SH_SSH_KEY_PATH=/path/to/ssh/key  # Absolute path to private key
ODOO_SH_SSH_PORT=22                    # Optional: default 22
ODOO_SH_SSH_PASSPHRASE=                # Optional: if key has passphrase
SSH_TIMEOUT=30000                      # Optional: milliseconds
LOG_LEVEL=info                         # Optional: debug, info, warn, error

⚠️ Important Note

Never commit your private SSH key. Use absolute paths and secure permissions (chmod 600).

MCP Client Configuration

Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "odoo-sh": {
      "command": "node",
      "args": [
        "/absolute/path/to/Odoo.sh MCP/dist/index.js"
      ],
      "env": {
        "ODOO_SH_SSH_HOST": "project-name.dev.odoo.com",
        "ODOO_SH_SSH_USER": "BUILD_ID",
        "ODOO_SH_SSH_KEY_PATH": "/absolute/path/to/ssh/key"
      }
    }
  }
}

Cline (VSCode)

Add to VSCode settings:

{
  "cline.mcpServers": {
    "odoo-sh": {
      "command": "node",
      "args": ["/absolute/path/to/Odoo.sh MCP/dist/index.js"],
      "env": {
        "ODOO_SH_SSH_HOST": "${env:ODOO_SH_SSH_HOST}",
        "ODOO_SH_SSH_USER": "${env:ODOO_SH_SSH_USER}",
        "ODOO_SH_SSH_KEY_PATH": "${env:ODOO_SH_SSH_KEY_PATH}"
      }
    }
  }
}

💡 Usage Tip

Use absolute paths to dist/index.js.

💻 Usage Examples

Once configured, your AI assistant can directly utilize Odoo.sh tools:

Basic Operations

• Check project info:

"Show me my Odoo.sh project information"

• Check build status:

"What's the status of recent builds?"

• View build logs:

"Show me the recent Odoo logs"

Building Custom Apps (NEW)

• Create a new Odoo module:

"Create a new custom Odoo module called 'my_custom_app' with the basic structure"

The AI agent can perform the following steps:

1. Create directory structure: my_custom_app/, my_custom_app/models/, etc.
2. Create __init__.py, __manifest__.py files.
3. Create model files with Python code.
4. Create XML view files.
5. Stage all files with git add.
6. Commit with a descriptive message.
7. Push to trigger an Odoo.sh build.

• Modify existing module:

"Add a new field 'phone' to the Partner model in my_custom_app"

• Complete development workflow example:

"I want to build a customer feedback module:
1. Create module structure for 'customer_feedback'
2. Add a Feedback model with fields: customer_id, rating, comment, date
3. Create list and form views
4. Add menu items
5. Commit and push to main branch"

📚 Documentation

Available Tools

The server offers 19 tools for Odoo.sh operations via SSH, including comprehensive Git workflow support for building custom apps:

Project & Branches

• get_project_info: Retrieve project information, including the branch list.
  • Returns: project name, repository, list of branches.
  • 💡 Use this to list branches (recommended over list_branches).
• get_current_branch: Get the currently checked-out branch.
  • Returns: current branch name.
• list_branches: List branches with commit information.
  • Returns: branch names with the last commit hash and message.
  • ⚠️ Known issue: May not work in some MCP clients (use get_project_info instead).

Builds

• get_build_history: Obtain the commit/build history for a branch.
  • Parameters: branch (e.g., "main"), limit (default: 10).
  • Returns: commit hash, author, date, message.
• trigger_build: Trigger a new build by creating an empty commit.
  • Parameters: branch.
  • Returns: git push output.

Database

• list_databases: List all PostgreSQL databases.
  • Returns: database names and sizes.

Logs & Shell

• get_logs: Retrieve Odoo logs from the server.
  • Parameters: log_type ("odoo", "install", "pip"), lines (default: 100).
  • Returns: log entries with timestamps.
• execute_odoo_shell: Execute Python code in the Odoo shell.
  • Parameters: python_code.
  • Returns: shell output.

System

• get_system_info: Get system information.
  • Returns: hostname, uptime, disk usage, memory, Python version, Odoo version.

Git Workflow & File Management (NEW - for building custom apps)

• git_status: Get the git status, showing modified, staged, and untracked files.
  • Returns: git status output.
• write_file: Create or update a file with the given content.
  • Parameters: filePath (relative to ~/src/user), content.
  • Returns: success message.
  • 💡 Uses base64 encoding to safely transfer file content via SSH.
• read_file: Read the contents of a file.
  • Parameters: filePath (relative to ~/src/user).
  • Returns: file content.
• list_files: List files and directories in a path.
  • Parameters: dirPath (optional, default: ., relative to ~/src/user).
  • Returns: ls -la output.
• create_directory: Create a directory (including parent directories).
  • Parameters: dirPath (relative to ~/src/user).
  • Returns: success message.
• git_add: Stage files for commit.
  • Parameters: files (array of file paths or . for all).
  • Returns: git add output.
• git_commit: Commit staged changes.
  • Parameters: message.
  • Returns: git commit output.
• git_push: Push commits to the remote repository.
  • Parameters: branch (optional, defaults to the current branch).
  • Returns: git push output.
• git_checkout: Switch to a branch or create a new branch.
  • Parameters: branch, createNew (optional, default: false).
  • Returns: git checkout output.
• git_pull: Pull changes from the remote repository.
  • Returns: git pull output.

Prompts

Guided workflows for common tasks:

check_build_status

Comprehensive build status check for a project:

• Lists all branches.
• Shows recent builds.
• Highlights failures.
• Displays build trends.

Usage: check_build_status with project_id.

deploy_workflow

Step-by-step deployment guidance:

• Checks the current branch status.
• Verifies pending builds.
• Validates database backups.
• Guides through the deployment process.
• Provides verification steps.

Usage: deploy_workflow with project_id and environment.

🔧 Technical Details

Development

Scripts

# Build TypeScript
npm run build

# Development mode (auto-rebuild)
npm run dev

# Run tests
npm test

# Watch tests
npm test:watch

# Lint code
npm run lint

# Format code
npm run format

Project Structure

odoo-mcp-server/
├── src/
│   ├── index.ts          # MCP server implementation
│   └── odoo-client.ts    # Odoo.sh API client
├── tests/                # Test files (to be added)
├── docs/
│   ├── Runbook.md        # Setup and usage guide
│   ├── DECISIONS.md      # Architectural decisions
│   ├── Troubleshooting.md # Known issues
│   └── Docs-Index.md     # External references
├── dist/                 # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── .env.example

Testing

Tests are located in the tests/ directory. Run with:

npm test

Troubleshooting

Common Issues

• 1. SSH Connection Failed

Error: SSH connection error

Solution:

• Verify that the SSH key path is correct and absolute.
• Check key permissions: chmod 600 /path/to/key (Unix) or icacls (Windows).
• Verify the hostname format: BUILD_ID@project-name.dev.odoo.com.
• Test manually: ssh -i /path/to/key BUILD_ID@host.
• 2. list_branches Tool Not Working in Warp

Empty response from list_branches

Solution: Use get_project_info instead - it returns the branch list and works reliably in all MCP clients.

• 3. Antivirus Blocking SSH Commands (Windows)

Bitdefender: Malicious command line detected

Solution: Whitelist the SSH command or the project directory in your antivirus settings.

• 4. Server Not Appearing
  • Verify JSON syntax in the MCP client config.
  • Check the absolute path to dist/index.js.
  • Verify that environment variables are set.
  • Restart the MCP client.
• 5. Module Not Found

Error: Cannot find module '@modelcontextprotocol/sdk/server/index.js'

Solution: Run npm install and npm run build.

See docs/Troubleshooting.md for more issues and solutions.

Architecture

Technology Stack

• Runtime: Node.js >= 18.0.0
• Language: TypeScript 5.3
• Protocol: Model Context Protocol (MCP)
• SSH Client: OpenSSH (subprocess)
• Validation: Zod
• Transport: stdio

Design Decisions

Key architectural decisions are documented in docs/DECISIONS.md and docs/SSH-MIGRATION.md:

• dec-20251107T160000Z-ssh-over-api: SSH-based access instead of REST API.
• Why the OpenSSH subprocess was chosen over the Node.js ssh2 library.
• How Windows % escaping issues were resolved.
• Git command optimization for performance.

🤝 Contributing

Contributions are welcome! Please:

1. Follow the existing code style (use npm run format).
2. Add tests for new features.
3. Update documentation (README, Runbook, DECISIONS.md).
4. Document issues in Troubleshooting.md.

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• Odoo.sh Documentation: https://www.odoo.com/documentation/17.0/administration/odoo_sh.html
• MCP Specification: https://spec.modelcontextprotocol.io/
• MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk

Maintained by: Odoo MCP Server Contributors
Version: 0.1.0