tideway-mcp

A read-only Model Context Protocol (MCP) server for BMC Discovery.

It exposes the BMC Discovery /data/search REST API endpoint as MCP tools so that an LLM can query discovered infrastructure data using the Tideway Query Language (TQL).

---

Features

Tool	Description
get_taxonomy	Returns all node kinds in the BMC Discovery taxonomy with their key attributes and relationships. Call this first to understand the data model.
get_node_kind_details	Returns detailed information about a single node kind (e.g. Host, DatabaseInstance).
get_query_help	Returns the TQL syntax reference with worked examples.
search_discovery_data	Executes a TQL query against the live BMC Discovery /data/search endpoint and returns results as JSON.

---

Requirements

• Python ≥ 3.10
• A running BMC Discovery (on-premises or Helix) instance accessible from the machine running the server.

---

Installation

pip install .

Or, for development (editable install):

pip install -e .

---

Configuration

The server is configured entirely through environment variables (or a .env file in the working directory).

Variable	Required	Description
TIDEWAY_HOST	Yes	Hostname or IP of the BMC Discovery appliance (e.g. discovery.example.com).
TIDEWAY_TOKEN	One of	Bearer token for API authentication.
TIDEWAY_USERNAME	One of	Username for basic-auth (used together with TIDEWAY_PASSWORD).
TIDEWAY_PASSWORD	One of	Password for basic-auth.
TIDEWAY_SSL_VERIFY	No	Set to false to disable TLS certificate verification (useful for self-signed certs). Default: true.
TIDEWAY_API_VERSION	No	REST API version string. Default: v1.1.

Create a .env file (never commit this):

TIDEWAY_HOST=discovery.example.com
TIDEWAY_TOKEN=your-api-token-here
# TIDEWAY_SSL_VERIFY=false   # uncomment for self-signed certs

---

Running the server

Stdio transport (default – for MCP clients like Claude Desktop)

tideway-mcp

If you are running directly from a repo checkout without installing the package, you can also use the repo-root wrapper script:

./tideway-mcp

That wrapper prefers ./venv/bin/python when present and otherwise falls back to python3 -m tideway_mcp.server.

Claude Desktop configuration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "tideway": {
      "command": "tideway-mcp",
      "env": {
        "TIDEWAY_HOST": "discovery.example.com",
        "TIDEWAY_TOKEN": "your-api-token-here"
      }
    }
  }
}

LM Studio configuration

If LM Studio is configured to execute a file path directly from the repo, point it at the repo-root wrapper instead of a non-existent built binary:

{
  "mcpServers": {
    "tideway": {
      "command": "/absolute/path/to/tideway-mcp/tideway-mcp",
      "env": {
        "TIDEWAY_HOST": "discovery.example.com",
        "TIDEWAY_TOKEN": "your-api-token-here"
      }
    }
  }
}

An equally valid alternative is to point LM Studio at the virtualenv entrypoint created by pip install -e .:

{
  "mcpServers": {
    "tideway": {
      "command": "/absolute/path/to/tideway-mcp/venv/bin/tideway-mcp",
      "env": {
        "TIDEWAY_HOST": "discovery.example.com",
        "TIDEWAY_TOKEN": "your-api-token-here"
      }
    }
  }
}

---

Example interactions

User: Find all Linux hosts discovered by BMC Discovery.

The LLM will:

1. Call get_taxonomy() to understand the Host node kind.
2. Call get_query_help() to learn TQL syntax.
3. Call search_discovery_data(query="search Host where os_type = 'Linux'").

User: List all Oracle database instances and their ports.

search_discovery_data(
    query="search DatabaseInstance where type = 'Oracle' show name, port, version"
)

---

Query language reference

See the BMC Discovery TQL documentation or call the get_query_help tool for an inline reference.

---

License

MIT