Coupler.io official MCP server

The Coupler.io MCP Server is a Model Context Protocol (MCP) server that provides seamless integration with Coupler.io APIs.

With Coupler.io MCP Server, you can analyze multi-channel marketing, financial, sales, e-commerce, and other business data within Claude by connecting to your Coupler.io data flows — query marketing, sales, and finance metrics from hundreds of sources. Fetch and transform raw data from platforms like Google Ads, Facebook, HubSpot, and Salesforce into actionable intelligence for smarter, faster decision-making with accurate, up-to-date business information.

Use Cases

Get data from your Coupler.io data flows and ask your AI tool questions about it, like you would ask your 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.

Prerequisites

1. Install Docker to run the server in a container.

2. Make sure Docker is running.

3. Get a Coupler.io Personal Access Token.

OR

Build a .mcpb 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": ""
      }
    }
  }
}

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.

Tools

Data flows

• get-data - Gets the result of a data flow run as a SQLite file and executes a read-only query on it. To get the data from a Coupler.io data flow, you need the data flow to have an AI destination.
• dataflowId: Data flow ID (string, required)
• executionId: Data flow run ID (string, required)
• query: Query to run on the data flow SQLite file (string, required)

• get-schema - Gets the data flow schema file. Currently, only data flows built from a dashboard or dataset template are supported.
• dataflowId: Data flow ID (string, required)
• executionId: Data flow run ID (string, required)

• list-dataflows – Gets the list of data flows that have an AI destination.
• dataflowId: Data flow ID (string, required)
• executionId: Data flow run ID (string, required)

• get-dataflow – Gets the metadata about the data flow, such as sources, data connections, last successfull execution, and error details (if present).
• dataflowId: Data flow ID (string, required)
• executionId: Data flow run ID (string, required)

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

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

Caveat: 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, therefore logs must go to a file. This may come in handy when 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'd likely want to mount a dir at /app/log to be able to access the logs it generates.

Working with the development Docker image

Build Docker image for development:

bin/build_image

You can now run the container with the MCP inspector for debugging in UI mode:

npm run inspect:docker

Or run the container within Claude Desktop, configured with your .env.local file in the project.

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=

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",
        "--pull",
        "always",
        "-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": ""
      }
    }
  }
}

[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 looks like this:

• 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 should now be able to 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 (MCPB)

Build & self-sign

bin/build_mcpb # => mcpb_output/coupler-mcp.mcpb
npm run mcpb:selfsign

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

License

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