Skip to content
Back to search

doql-mcp-server

An MCP server that exposes read-only Device42 DOQL queries and the live Device42 data dictionary to MCP clients such as VS Code Copilot Chat or Claude Desktop.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/skywalkr--doql-mcp-server/badge.svg)](/listings/skywalkr--doql-mcp-server)

HTML

<a href="/listings/skywalkr--doql-mcp-server"><img src="/api/listings/skywalkr--doql-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip install .

For development, install in editable mode:

pip install -e .

This installs the `doql-mcp` command.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 152 lines
  1. # doql-mcp
  2. An [MCP](https://modelcontextprotocol.io) server that exposes read-only [Device42](https://www.device42.com) DOQL queries and the live Device42 data dictionary to MCP clients such as VS Code Copilot Chat or Claude Desktop.
  3. ## Features
  4. - **Run DOQL queries** with the `query_doql` tool. Only a single `SELECT` statement is accepted; semicolons and other statements are rejected.
  5. - **Discover views and columns** with the `list_schemas` and `get_schema` tools, which read the dictionary loaded from the Device42 instance at startup.
  6. - **Browse the data dictionary** as MCP resources: `device42://dictionary` for the full dictionary and `device42://schema/<view>` for each view.
  7. - **DOQL workflow prompt** named `device42-doql`, served from the skill file packaged at `src/doql_mcp/skills/device42-doql/SKILL.md`.
  8. - **Two transports**: `stdio` (default) for local clients and `streamable-http` for remote or containerized use.
  9. ## Requirements
  10. - Python 3.10 or newer
  11. - Network access to a Device42 instance
  12. - Device42 credentials: an API Client key and secret, or a username and password
  13. ## Installation
  14. ```bash
  15. pip install .
  16. ```
  17. For development, install in editable mode:
  18. ```bash
  19. pip install -e .
  20. ```
  21. This installs the `doql-mcp` command.
  22. ## Configuration
  23. The server reads its configuration from environment variables.
  24. | Variable | Required | Default | Description |
  25. | --- | --- | --- | --- |
  26. | `D42_BASE_URL` | Yes | | Base URL of the Device42 instance, for example `https://d42.example.com`. |
  27. | `D42_CLIENT_KEY` | One auth pair | | API Client key. Used with `D42_CLIENT_SECRET` to request a bearer token. |
  28. | `D42_CLIENT_SECRET` | One auth pair | | API Client secret. Must be set together with `D42_CLIENT_KEY`. |
  29. | `D42_USERNAME` | One auth pair | | Username for HTTP basic auth. Used with `D42_PASSWORD`. |
  30. | `D42_PASSWORD` | One auth pair | | Password for HTTP basic auth. Used with `D42_USERNAME`. |
  31. | `D42_VERIFY_SSL` | No | `true` | Set to `false` to skip TLS certificate verification. Accepts `1`, `true`, `yes`, or `on` as true. |
  32. | `D42_TIMEOUT` | No | `30` | HTTP timeout in seconds. |
  33. If both an API Client pair and a username/password pair are set, the API Client pair is used.
  34. ## Usage
  35. Start the server with the default stdio transport:
  36. ```bash
  37. export D42_BASE_URL=https://d42.example.com
  38. export D42_CLIENT_KEY=your-key
  39. export D42_CLIENT_SECRET=your-secret
  40. doql-mcp
  41. ```
  42. Serve over streamable HTTP instead:
  43. ```bash
  44. doql-mcp --transport streamable-http --host 127.0.0.1 --port 8000
  45. ```
  46. | Option | Default | Description |
  47. | --- | --- | --- |
  48. | `--transport` | `stdio` | `stdio` or `streamable-http`. |
  49. | `--host` | `127.0.0.1` | Bind address for `streamable-http`. |
  50. | `--port` | `8000` | Port for `streamable-http`. |
  51. On startup the server downloads the data dictionary from Device42 and fails if it cannot. Logs are written to stderr, so stdout stays clean for the stdio transport.
  52. You can also run the package as a module with `python -m doql_mcp`.
  53. ### MCP client configuration
  54. Example stdio configuration for an MCP client:
  55. ```json
  56. {
  57. "mcpServers": {
  58. "device42-doql": {
  59. "command": "doql-mcp",
  60. "env": {
  61. "D42_BASE_URL": "https://d42.example.com",
  62. "D42_CLIENT_KEY": "your-key",
  63. "D42_CLIENT_SECRET": "your-secret"
  64. }
  65. }
  66. }
  67. }
  68. ```
  69. ## Tools
  70. | Tool | Arguments | Description |
  71. | --- | --- | --- |
  72. | `query_doql` | `query: str`, `output_type: "json" \| "csv"` (default `json`) | Runs a read-only DOQL `SELECT` and returns the result. |
  73. | `list_schemas` | `search: str` (optional) | Lists view names, filtered by a case-insensitive substring. |
  74. | `get_schema` | `name: str` | Returns the dictionary entry for one view, including its columns and data types. |
  75. Example DOQL query:
  76. ```
  77. SELECT name FROM view_device_v2 LIMIT 5
  78. ```
  79. ## Docker
  80. Build the image:
  81. ```bash
  82. docker build -t doql-mcp .
  83. ```
  84. Run it with the streamable HTTP transport on port 8000, which is the image default:
  85. ```bash
  86. docker run --rm -p 8000:8000 \
  87. -e D42_BASE_URL=https://d42.example.com \
  88. -e D42_CLIENT_KEY=your-key \
  89. -e D42_CLIENT_SECRET=your-secret \
  90. doql-mcp
  91. ```
  92. The container runs as a non-root user (`app`, UID 1000).
  93. ## Project layout
  94. ```
  95. src/doql_mcp/
  96. __main__.py Entry point for `python -m doql_mcp`
  97. cli.py Argument parsing, startup, and transport selection
  98. client.py Async HTTP client for the Device42 API (auth, dictionary, DOQL)
  99. config.py Environment-based settings and authentication checks
  100. dictionary.py Converts the dictionary payload into a view-name mapping
  101. server.py MCP server, tools, resources, and prompt
  102. skills/ DOQL workflow guide served as the device42-doql prompt
  103. data/dd.json Sample data dictionary snapshot (not read at runtime)
  104. .github/skills/ Copy of the DOQL skill for VS Code Copilot (keep in sync with skills/)
  105. Dockerfile Container image definition
  106. ```
  107. ## Development
  108. Run the server locally against a Device42 instance using the configuration above. The project has no test suite yet.
  109. ## Notes
  110. - The schema comes from the live Device42 instance and can differ between deployments.
  111. - DOQL result sets can be large. Use `LIMIT`, select only the columns you need, and prefer `csv` for bulk exports.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.