Coupler Io MCP Server

🚀 Coupler.io official MCP server

The Coupler.io MCP Server is a Model Context Protocol (MCP) server that offers seamless integration with Coupler.io APIs. It enables you to analyze multi - channel marketing, financial, sales, e - commerce, and other business data within Claude by connecting to your Coupler.io data flows. You can query marketing, sales, and finance metrics from hundreds of sources, and transform raw data from platforms like Google Ads, Facebook, HubSpot, and Salesforce into actionable intelligence, facilitating smarter and faster decision - making with accurate and up - to - date business information.

🚀 Quick Start

Prerequisites

1. Install Docker to run the server in a container.
2. Ensure Docker is running.
3. Obtain a Coupler.io Personal Access Token.

OR

Build a .dxt file using the command below and use it to install the local MCP.

Running the server

Claude Desktop

{
  "mcpServers": {
    "coupler": {
      "command": "docker",
      "args": [
        "run",
        "--pull=always",
        "-e",
        "COUPLER_ACCESS_TOKEN",
        "--rm",
        "-i",
        "ghcr.io/railsware/coupler-io-mcp-server"
      ],
      "env": {
        "COUPLER_ACCESS_TOKEN": "<your_token>"
      }
    }
  }
}

⚠️ Important Note

"--pull=always" will ensure you always have the latest image by pulling it from the registry. Remove this line if you're offline or if you specifically want to use the image you've already pulled previously.

✨ Features

Use Cases

Retrieve data from your Coupler.io data flows and pose questions to your AI tool, similar to how you'd consult a fellow data analyst:

Marketing

1. What's our overall customer acquisition cost across all paid channels this quarter compared to last quarter? I need this for the board meeting.
2. Show me the ROI breakdown by marketing channel for the past 6 months. I need to reallocate our annual budget.
3. Which campaigns are contributing most to our pipeline revenue? I want to double down on what's working.

Sales

1. Can you pull the sales pipeline report for this month? I need to see how many deals are in each stage and the total value at each stage.
2. What are our conversion rates from lead to opportunity and from opportunity to closed - won for the last quarter? How do they compare to our targets?
3. How many deals are expected to close this month based on their probability scores? What's our forecasted revenue vs our monthly target?

Finance

1. Check the profit for this quarter, compare it to last quarter, and provide a breakdown by department.
2. Could you provide a cash flow report for the last 30 days, including all incoming and outgoing transactions?
3. Share the current accounts receivable status and tell me how many overdue invoices we have and which customers owe the most.

📦 Installation

Development

Install NodeJS

asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git
asdf install

Install dependencies

npm install

Install Git hooks

lefthook install

Set environment variables

cp .env.example .env.local

💻 Usage Examples

Work with a raw server

Run the MCP server

# Use `--silent` flag to prevent NPM logging to STDOUT which breaks server transport
npm run --silent dev

Run MCP server inspector for debugging

⚠️ Important Note

Make sure to keep only a single inspector tab open at all times, until this inspector bug is fixed.

# Run this and follow the instructions to view the inspector
npm run inspect:node

Tail logs

Our local MCP server uses STDIO transport, so logs must go to a file. This can be useful for debugging.

tail -f log/development.log | npx pino-pretty

You can also optionally capture STDIO messages in the log file by setting LOG_STDIO = 1 when running the server. If you're debugging a containerized server, you'll likely want to mount a dir at /app/log to access the logs it generates.

Working with the development Docker image

Build Docker image for development

bin/build_image

Run the container with the MCP inspector for debugging in UI mode

npm run inspect:docker

Run the container within Claude Desktop

Grab the absolute path to your env file realpath .env.local. Navigate to Settings > Developer > Edit Config. Edit your claude_desktop_config.json, add an entry for our server:

{
  "mcpServers": {
    "coupler-io-mcp-server-development": {
      "command": "docker",
      "args": [
        "run",
        "--env-file",
        "/path/to/your/.env.local",
        "--add-host",
        "storage.test=host-gateway",
        "--add-host",
        "lvh.me=host-gateway",
        "--rm",
        "-i",
        "coupler-io-mcp-server-development"
      ]
    }
  }
}

Or just run the image with Docker

docker run --env-file .env.local \
  --add-host storage.test=host-gateway \
  --add-host lvh.me=host-gateway \
  --rm \
  -i \
  coupler-io-mcp-server-development

Using MCP inspector

Use MCP inspector in CLI mode for smoke testing the server with a short feedback loop:

# List tools
npx @modelcontextprotocol/inspector --cli npm run dev --method tools/list

# Call list-dataflows tool
npx @modelcontextprotocol/inspector --cli npm run dev --method tools/call --tool-name list-dataflows

# Call get-schema tool
npx @modelcontextprotocol/inspector --cli npm run dev --method tools/call --tool-name get-schema --tool-arg dataflowId=<your data flow ID>

Testing the Docker image against Coupler.io staging

We build and publish a Docker image of our MCP server, tagged edge, on every push to the main branch.

Configure Claude Desktop to run the Docker container against Coupler.io staging. Navigate to Settings > Developer > Edit Config. Edit your claude_desktop_config.json, add an entry for the staging server:

{
  "mcpServers": {
    "coupler-io-mcp-server-staging": {
      "command": "docker",
      "args": [
        "run",
        "-e",
        "COUPLER_ACCESS_TOKEN",
        "--env",
        "COUPLER_API_HOST=https://app.couplerstaging.dev/mcp",
        "--rm",
        "-i",
        "ghcr.io/railsware/coupler-io-mcp-server:edge"
      ],
      "env": {
        "COUPLER_ACCESS_TOKEN": "<your_coupler_access_token_from_staging>"
      }
    }
  }
}

💡 Usage Tip

[Optional] Enable logging for debugging by adding the following args:

        "--env",
        "LOG_LEVEL=debug",
        "--env",
        "LOG_STDIO=1",

Building and pushing a release image

The development cycle is as follows:

• Open a PR with changes.
• Use the pr - N - tagged image to debug and test your changes.
• Merge the PR to main.
• Test the edge image.
• Build and push a release image tagged as latest.

To build and push a release image:

• Draft a new release.
• Specify a new tag to be created on publish. Use semver.
• Target: main branch.
• Generate or write release notes.
• Click "Publish release".
• Check the docker image workflow progress.

You can now smoke - test the release image:

# Pull the `latest` image
docker pull ghcr.io/railsware/coupler-io-mcp-server

Run the release image with Claude Desktop and other supported clients.

Claude Desktop extension (DXT)

Build & self - sign

bin/build_dxt # => dxt_output/coupler-mcp.dxt
npm run dxt:selfsign

You can either install the .dxt file or use the contents of dxt/ dir to load an unpacked extension from the Developer menu.

📚 Documentation

Tools

📄 License

This project is licensed under the terms of the MIT open source license. Please refer to MIT for the full terms.