Set up the Tulip MCP

Prev Next

How do I set up the Tulip MCP?

Detailed setup documentation for the Tulip MCP is available in the official repository: https://github.com/tulip/tulip-mcp/tree/master

The setup for the Tulip MCP has been streamlined. The new process involves three key steps:

  1. Configure Your Credentials
  2. Run the Server
  3. Connect to an MCP Client

Prerequisites

Before you begin, ensure you have Node.js installed on your system. This is required to run the server.

Checking your version of npm and Node.js
Run the following commands in your terminal/Windows Terminal (Command Prompt, PowerShell):

node -v
npm -v

If you get a version name then you are good to go, and you can continue for step 1.
If not, head to node.js and install the latest version for your operating system.

Configure Your Tulip API Credentials

To connect to Tulip via API, you need to create a .env file that securely stores your API credentials.

1. Create a Configuration Folder

Choose or create a folder where you want to store your environment configuration file.

Guide: Create a .env File

This file will store your Tulip credentials. An example .env file is available here.

Mac Users:

  1. Open Terminal and run the following commands:
touch .env
nano .env
  1. Paste the credentials template (in the next step) into the new file.
  2. After adding your credentials, follow the save instructions below.

Windows Users:

  1. Open Notepad.
  2. Paste the credentials template (in the next step) into the new file.
  3. After adding your credentials, follow the save instructions below.

2. Add Your Tulip Credentials

Copy and paste the following into the .env file, replacing the placeholder values with your actual credentials:

TULIP_API_KEY=your_api_key_here
TULIP_API_SECRET=your_api_secret_here
TULIP_BASE_URL=https://your-instance.tulip.co
TULIP_WORKSPACE_ID=your_workspace_id_here_if_using_account_api_key
  • TULIP_BASE_URL: This is the URL you use to access Tulip.
    Example: https://my-company.tulip.co

  • TULIP_WORKSPACE_ID: Found in your Tulip URL after /w/.
    Example: In https://my-company.tulip.co/w/DEFAULT, the workspace ID is DEFAULT.

Important

Only include TULIP_WORKSPACE_ID if you are using an Account API Key (from Account Settings).

If you are using a Workspace API Key (from Workspace Settings), you can leave this field blank.

Save your file, and make sure the file is located in the folder you have specified.

3. Run the Server

Once your .env file is configured, you can start the server.

Open your terminal or command prompt, navigate to the folder containing your .env file, and run the following command:

npx @tulip/mcp-server

The command will download the latest version of the Tulip MCP server and start it. The server is now running and ready to be connected to an MCP client.

4. Connect to the Tulip MCP

When an MCP client runs the server, it may not be in the same directory as your .env file, so it won't find the credentials automatically. To fix this, you must provide the full path to your .env file using the --env flag in the client's configuration.

Guide: Finding Your .env File Path

  1. Navigate to the folder where you created your .env file.
  2. On Windows: Right-click the .env file while holding down the Shift key, then select "Copy as path".
  3. On macOS: Right-click the .env file, hold down the Option key, then select "Copy .env as Pathname".
  4. You will use this copied path in the client configuration below.

Guide: Claude Desktop

  1. From the Claude Desktop menu bar, select Settings... > Developer > Edit Config.
  2. This will open the claude_desktop_config.json file.
  3. Add the server configuration inside the mcpServers object. You must replace "C:\\path\\to\\your\\.env" with the actual path you copied.
    {
      "mcpServers": {
        "tulip-mcp": {
          "command": "npx",
          "args": [
            "@tulip/mcp-server",
            "--env",
            "C:\\path\\to\\your\\.env"
          ]
        }
      }
    }
    
  4. Save the file and restart Claude Desktop.

For more details, see the official Claude Desktop MCP Quickstart.

Cursor

For the easiest setup, click the button below. This will pre-fill the command in Cursor.

Connect to Cursor

After clicking the button, you must replace the placeholder text (REPLACE_WITH_YOUR_ENV_FILE_PATH_HERE) with the full path to your .env file that you copied earlier.

Advanced Configuration

Getting Tulip API Credentials

You can create API credentials (Tokens) from your Tulip instance settings.

  1. Log in: Access your Tulip instance.
  2. Navigate to API Tokens: Go to Settings > API Tokens.
  3. Create a new API token: Generate a new token, giving it a descriptive name (e.g., "MCP Server").
  4. Configure Scopes: Grant the token the necessary permissions (scopes). A good starting set of scopes for basic access is:
    stations:read, users:read, tables:read, machines:read, apps:read, urls:sign
  5. Copy credentials: Copy the generated API Key and Secret and paste them into your .env file.

Tool Selection Configuration

By default, for safety, the server enables only read-only and table tools. You can customize which tools are available using the ENABLED_TOOLS environment variable in your .env file.

The ENABLED_TOOLS variable accepts a comma-separated list that can include:

  • Individual tool names: Specific tools like listStations.
  • Categories: Security-based groupings (read-only, write, admin).
  • Types: Resource-based groupings (table, machine, user, app, interface, station, station-group, utility).

Examples:

# Enable all read and write operations
ENABLED_TOOLS=read-only,write

# Enable all tools related to tables and stations
ENABLED_TOOLS=table,station

# Enable specific tools
ENABLED_TOOLS=listStations,addRecord

# A recommended mixed approach
ENABLED_TOOLS=read-only,interface,station,user

# Enable everything (use with caution as this allows data deletion/archiving)
ENABLED_TOOLS=read-only,write,admin

Related Articles