# segment-mcp

A small, **read-only** MCP server for the [Twilio Segment Public API](https://docs.segmentapis.com/).
It only sends `GET` requests. It can list and inspect a workspace's Segment config but can never change it.

It lets Claude (or any MCP client) answer questions like "how is the Intercom destination configured?"
or "which destinations hang off this source?" straight from Segment, without clicking through the dashboard.

## Tools

| Tool | What it does |
|------|--------------|
| `list_sources` | All sources in the workspace |
| `get_source` | One source by id (incl. settings) |
| `list_destinations` | All destinations; optional `name` substring filter (e.g. `intercom`) and/or `sourceId` |
| `get_destination` | One destination by id, incl. full settings/config |
| `list_tracking_plans` | All tracking plans |
| `get_tracking_plan` | One tracking plan by id |
| `list_functions` | All functions; optional `resourceType` filter (`SOURCE`, `DESTINATION`, `INSERT_DESTINATION`, ...) |
| `get_function` | One function by id |
| `api_get` | Read-only escape hatch: GET any other Public API path (e.g. `/warehouses`) |

List tools follow cursor pagination, so they return every page.

## Setup

Requires Node.js 18 or later.

1. **Install:**
   ```sh
   git clone https://github.com/pedromfs/segment-mcp.git
   cd segment-mcp
   npm install
   ```
2. **Create a Segment API token** - in Segment: `Settings -> Access Management -> Tokens -> Create Token`.
   Give it a **read-only** role; this server never writes. `.env.example` has the step-by-step and a fix
   for `403 Forbidden`.
3. **Provide the token.** Either option works (the server reads the `.env` next to `index.mjs` first,
   then falls back to the ambient environment):
   - **A local `.env`** (gitignored, so the token never lands in the repo):
     ```sh
     cp .env.example .env   # then set SEGMENT_PUBLIC_API_TOKEN=sgp_...
     ```
   - **Or a shell export:**
     ```sh
     export SEGMENT_PUBLIC_API_TOKEN="sgp_..."
     ```
     A real shell value takes precedence over the `.env`.
4. **Register it with your MCP client.** For Claude Code, add it to a project's `.mcp.json`:
   ```json
   {
     "mcpServers": {
       "segment": {
         "type": "stdio",
         "command": "node",
         "args": ["/absolute/path/to/segment-mcp/index.mjs"]
       }
     }
   }
   ```
   or run `claude mcp add segment -- node /absolute/path/to/segment-mcp/index.mjs`.
   Restart the client so it picks up the server and the token.

## Local smoke test

```sh
SEGMENT_PUBLIC_API_TOKEN=sgp_... node index.mjs   # then speak MCP JSON-RPC over stdin
```

## Notes

- The base URL defaults to `https://api.segmentapis.com`; override it with `SEGMENT_PUBLIC_API_URL` if needed.
- Every request goes to that base URL. `api_get` takes a path, not a full URL, so the token is never sent to another host.
- If the token is missing, tools return an error rather than crashing the server.

## License

MIT