https://github.com/railsware/coupler-io-mcp-server
Coupler.io MCP server
https://github.com/railsware/coupler-io-mcp-server
Last synced: 12 months ago
JSON representation
Coupler.io MCP server
- Host: GitHub
- URL: https://github.com/railsware/coupler-io-mcp-server
- Owner: railsware
- License: mit
- Created: 2025-04-15T09:07:22.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-12T11:48:48.000Z (about 1 year ago)
- Last Synced: 2025-06-12T12:44:49.206Z (about 1 year ago)
- Language: TypeScript
- Size: 436 KB
- Stars: 0
- Watchers: 8
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-servers - **coupler-io-mcp-server** - Coupler.io MCP server `typescript` `mcp` `server` `npm install railsware/coupler-io-mcp-server` (🌐 Web Development)
README
[](https://github.com/railsware/coupler-io-mcp-server/actions/workflows/lint-and-test.yml)
# 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](https://www.docker.com/) to run the server in a container.
2. Make sure Docker is running.
3. Get a [Coupler.io Personal Access Token](https://app.coupler.io/app/ai_features)
## Running the server
### Claude Desktop
```json
{
"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. 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:
```shell
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git
asdf install
```
Install dependencies:
```shell
npm install
```
Install Git hooks:
```shell
lefthook install
```
Set environment variables:
```shell
cp .env.example .env.local
```
### Work with a raw server
Run the MCP server:
```shell
npm run dev
```
#### Run [MCP server inspector](https://github.com/modelcontextprotocol/inspector) for debugging
Caveat: make sure to keep only a single inspector tab open at all times, until [this inspector bug](https://github.com/modelcontextprotocol/inspector/issues/302) is fixed.
```shell
# 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.
```shell
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:
```shell
bin/build_image
```
You can now run the container with the MCP inspector for debugging in UI mode:
```shell
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:
```json
{
"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](https://github.com/modelcontextprotocol/inspector/blob/24e8861a88f843d57cdb637a5ae3afd0e528c5f3/README.md#cli-mode) for smoke testing the server with a short feedback loop:
```shell
# 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 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:
```json
{
"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": ""
}
}
}
}
```
[Optional] Enable logging for debugging by adding the following args:
```json
"--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](https://github.com/railsware/coupler-io-mcp-server/releases/new?target=main)
- specify a new tag to be created on publish. Use [semver](https://semver.org/)
- Target: `main` branch
- Generate or write release notes
- click "Publish release"
- check [the docker image workflow](https://github.com/railsware/coupler-io-mcp-server/actions/workflows/publish-docker-image.yml) progress
You should now be able to smoke-test the release image.
```shell
# 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](./LICENSE) for the full terms.