mcp-vtenext

VTENext CRM用MCPサーバー — Claudeやその他のMCP互換クライアント向けにWebService APIをツールとして公開します。

要件

• Node.js 18以上

• 実行中のVTENextインスタンス（セルフホストまたはDocker — ../docker を参照）

セットアップ

cd mcp/vtenext/server
npm install
cp .env.example .env

.env を編集します：

VTENEXT_URL=http://your-vtenext-instance
VTENEXT_USERNAME=admin
VTENEXT_ACCESS_KEY=your_access_key
READ_ONLY=false

アクセスキーは、VTENextの 管理 → ユーザー → [ユーザー] → アクセスキー にあります。

読み取り専用モード

VTENextへの書き込み操作を禁止するには READ_ONLY=true を設定します。有効にすると、ツール create_opportunita、update_opportunita、add_nota_opportunita はデータを書き込まずにエラーを返します。

これは、CRMデータの読み取りのみを行うAIボットや自動エージェントがサーバーを使用する場合に便利です。フルアクセス可能なインスタンスと並行して読み取り専用インスタンスを実行するには、MCP設定を介して変数を渡します：

{
  "mcpServers": {
    "vtenext-bot": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp/vtenext/server/index.js"],
      "env": {
        "VTENEXT_URL": "http://your-vtenext-instance",
        "VTENEXT_USERNAME": "admin",
        "VTENEXT_ACCESS_KEY": "your_access_key",
        "READ_ONLY": "true"
      }
    }
  }
}

Claude Codeとの統合

プロジェクトルートの .mcp.json に以下を追加します：

{
  "mcpServers": {
    "vtenext": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp/vtenext/server/index.js"]
    }
  }
}

ツール

Opportunità (商談/Potentials)

Contatti (連絡先/Contacts)

Attività e note (活動とメモ)

Utilità (ユーティリティ)

認証

VTENextはvtiger WebServiceプロトコルを使用します：

1. GET /webservice.php?operation=getchallenge → トークン

2. MD5(トークン + アクセスキー) → ハッシュ化されたキー

3. POST /webservice.php （operation=login をフォームエンコードで送信） → sessionName

セッションは4分間キャッシュされます（トークンの有効期間は5分です）。

テスト

# Unit tests (no VTENext required)
npm test

# Integration tests (requires live VTENext at VTENEXT_URL)
npm run test:integration

ライセンス

MIT