Skip to content

WINDOWS_INSTALL.md

Latest commit

 

History

History
282 lines (206 loc) · 5.61 KB

WINDOWS_INSTALL.md

File metadata and controls

282 lines (206 loc) · 5.61 KB
Raw

Windows Installation Guide for Twenty MCP Server

This guide provides detailed instructions for Windows users to install and configure the Twenty MCP Server.

Prerequisites

Before starting, ensure you have:

  • ✅ Node.js 18+ installed - Download
  • ✅ Git installed - Download
  • ✅ Twenty CRM account with API access

Installation Options

Option 1: Using Git Bash (Recommended)

Git Bash provides a Linux-like environment on Windows, making it compatible with our install script.

  1. Open Git Bash (installed with Git for Windows)

  2. Clone and install:

# Clone the repository
git clone https://github.com/jezweb/twenty-mcp.git
cd twenty-mcp

# Make install script executable
chmod +x install.sh

# Run installation
./install.sh
  1. Note your path:
pwd
# Example: /c/Users/YourName/twenty-mcp
# Your server path: C:/Users/YourName/twenty-mcp/dist/index.js

Option 2: Using Command Prompt

If you prefer using Windows Command Prompt:

  1. Open Command Prompt (cmd.exe)

  2. Clone the repository:

git clone https://github.com/jezweb/twenty-mcp.git
cd twenty-mcp
  1. Install and build:
npm install
npm run build
  1. Get your path:
echo %cd%
REM Example: C:\Users\YourName\twenty-mcp
REM Your server path: C:\Users\YourName\twenty-mcp\dist\index.js

Option 3: Using PowerShell

For PowerShell users:

  1. Open PowerShell

  2. Clone and install:

git clone https://github.com/jezweb/twenty-mcp.git
cd twenty-mcp
npm install
npm run build
  1. Get your path:
Get-Location
# Example: C:\Users\YourName\twenty-mcp
# Your server path: C:\Users\YourName\twenty-mcp\dist\index.js

Configuration

Step 1: Create Configuration File

copy .env.example .env

Step 2: Edit Configuration

Open .env in your text editor (Notepad, VS Code, etc.) and add:

TWENTY_API_KEY=your-api-key-here
TWENTY_BASE_URL=https://api.twenty.com

Step 3: Set Environment Variables (Optional)

If you prefer using system environment variables:

Command Prompt:

set TWENTY_API_KEY=your-api-key-here
set TWENTY_BASE_URL=https://api.twenty.com

PowerShell:

$env:TWENTY_API_KEY="your-api-key-here"
$env:TWENTY_BASE_URL="https://api.twenty.com"

OAuth Setup (Advanced)

The Twenty MCP Server supports OAuth 2.1 authentication for enhanced security and multi-user support.

Step 1: Interactive OAuth Setup

Use the built-in OAuth setup CLI:

Git Bash (Recommended):

npm run setup:oauth

Command Prompt:

npm run setup:oauth

PowerShell:

npm run setup:oauth

Step 2: Manual OAuth Configuration

If you prefer manual configuration, add these to your .env file:

# OAuth Configuration
AUTH_ENABLED=true
REQUIRE_AUTH=false
AUTH_PROVIDER=clerk

# Clerk Configuration  
CLERK_PUBLISHABLE_KEY=pk_test_your_publishable_key
CLERK_SECRET_KEY=sk_test_your_secret_key
CLERK_DOMAIN=your-app.clerk.accounts.dev

# Security
API_KEY_ENCRYPTION_SECRET=your-32-byte-hex-string-here

# Server Configuration
MCP_SERVER_URL=http://localhost:3000
PORT=3000

Step 3: Windows Environment Variables for OAuth

Command Prompt:

set AUTH_ENABLED=true
set CLERK_SECRET_KEY=sk_test_your_secret_key
set CLERK_PUBLISHABLE_KEY=pk_test_your_publishable_key
set API_KEY_ENCRYPTION_SECRET=your-32-byte-hex-string

PowerShell:

$env:AUTH_ENABLED="true"
$env:CLERK_SECRET_KEY="sk_test_your_secret_key"
$env:CLERK_PUBLISHABLE_KEY="pk_test_your_publishable_key"
$env:API_KEY_ENCRYPTION_SECRET="your-32-byte-hex-string"

Step 4: Test OAuth Setup

# Test OAuth endpoints
npm run test:oauth

# Start server with OAuth
npm start

OAuth vs API Key Mode

Mode Setup Complexity Security Multi-user
API Key Simple Basic ❌ Single user
OAuth Moderate Enhanced ✅ Multiple users

Choose OAuth for:

  • Multi-user deployments
  • Enhanced security requirements
  • Production environments

Common Windows Issues

Issue: "Permission denied" errors

Solution: Run your terminal as Administrator

Issue: Path contains spaces

Solution: Use quotes in configurations:

{
  "args": ["C:/Program Files/twenty-mcp/dist/index.js"]
}

Issue: Backslashes in JSON

Solution: Use forward slashes or double backslashes:

  • ✅ C:/Users/Name/twenty-mcp/dist/index.js
  • ✅ C:\\Users\\Name\\twenty-mcp\\dist\\index.js
  • ❌ C:\Users\Name\twenty-mcp\dist\index.js

Issue: "node" command not found

Solution:

  1. Restart your terminal after installing Node.js
  2. Or add Node.js to PATH manually

IDE Configuration for Windows

Claude Desktop

  1. Find config file: %APPDATA%\Claude\claude_desktop_config.json

  2. Example configuration:

{
  "mcpServers": {
    "twenty-crm": {
      "command": "node",
      "args": ["C:/Users/YourName/twenty-mcp/dist/index.js"],
      "env": {
        "TWENTY_API_KEY": "your-key-here",
        "TWENTY_BASE_URL": "https://api.twenty.com"
      }
    }
  }
}

Cursor IDE

Use forward slashes in the configuration:

{
  "args": ["C:/Users/YourName/twenty-mcp/dist/index.js"]
}

Verification

Test your installation:

npm run validate

Expected output:

[SUCCESS] Configuration is valid! 🎉

Need Help?

  • Check the main README for more details
  • Run npm run validate to diagnose issues
  • Report problems at GitHub Issues