# mcp-hevo-service

A **read-only** MCP server for the [Hevo Data](https://hevodata.com) public API (v2.0).
Self-hosted: your API credentials stay on your machine and never reach a third party.
Exposes monitoring/inspection tools over pipelines, objects, destinations, models and
workflows. Every tool maps to a `GET` endpoint, so the server cannot mutate Hevo state.

## Quick start

```bash
git clone <this-repo>
cd mcp-hevo-service
pip install -r requirements.txt
cp .env.template .env   # then fill in your credentials
```

## Configuration

Generate an API Key + Secret in Hevo (**Account Settings > API**) and set them in `.env`:

| Variable | Description |
|---|---|
| `HEVO_API_KEY` | API key (used as the Basic-auth username). |
| `HEVO_API_SECRET` | API secret (used as the Basic-auth password). |
| `HEVO_REGION` | One of `us`, `eu`, `au`, `in`. Selects the base URL `https://<region>.hevodata.com/api/public/v2.0`. |

## Verify

```bash
python test_connection.py
```

Confirms the credentials authenticate against `GET /pipelines`. No MCP client needed.

## Register in an MCP client

```json
{
  "mcpServers": {
    "hevo": {
      "command": "/path/to/python3",
      "args": ["/path/to/mcp-hevo-service/server.py"]
    }
  }
}
```

## Tools

All tools are read-only (`GET`).

| Tool | Hevo endpoint |
|---|---|
| `list_pipelines` | `GET /pipelines` |
| `get_pipeline` | `GET /pipelines/{id}` |
| `get_pipeline_schedule` | `GET /pipelines/{id}/schedule` |
| `list_pipeline_objects` | `GET /pipelines/{id}/objects` |
| `get_pipeline_object_stats` | `GET /pipelines/{id}/objects/{object_name}/stats` |
| `list_destinations` | `GET /destinations` |
| `get_destination` | `GET /destinations/{id}` |
| `get_destination_table_stats` | `GET /destinations/{id}/tables/{table_name}/stats` |
| `list_models` | `GET /models` |
| `get_model` | `GET /models/{id}` |
| `list_workflows` | `GET /workflows` |
| `get_workflow` | `GET /workflows/{id}` |

## Security

- **Read-only by construction**: the client only issues `GET` requests and no write
  tool is registered. There is no way to start/pause/edit a pipeline through this server.
- Credentials are read from `.env` (gitignored) and sent as HTTP Basic auth directly to
  Hevo. They are not logged and never leave your host.

## Notes

Auth and endpoints follow the [official Hevo API docs](https://api-docs.hevodata.com/).
Pagination uses `limit` + `starting_after` where supported (see per-tool descriptions).