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.

⚠️ Alpha Software Warning
This repo contains early alpha software under active development. Features are incomplete and subject to breaking changes.

Use Cases

• Extracting and analyzing data from Coupler.io data flows.

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

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>"
      }
    }
  }
}

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. 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)
  • 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)

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:

npm run 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 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"
      ]
    }
  }
}

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 with 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>"
      }
    }
  }
}

[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.

License

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