@eamonboyle/mssql-mcp 1.5.0 → 1.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +329 -361
- package/dist/config.d.ts +30 -7
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +142 -34
- package/dist/config.js.map +1 -1
- package/dist/db.d.ts +4 -0
- package/dist/db.d.ts.map +1 -1
- package/dist/db.js +37 -23
- package/dist/db.js.map +1 -1
- package/dist/index.js +76 -43
- package/dist/index.js.map +1 -1
- package/dist/resourceRegistry.d.ts +6 -0
- package/dist/resourceRegistry.d.ts.map +1 -1
- package/dist/resourceRegistry.js +7 -1
- package/dist/resourceRegistry.js.map +1 -1
- package/dist/schema.d.ts.map +1 -1
- package/dist/schema.js +16 -20
- package/dist/schema.js.map +1 -1
- package/dist/tools/ListDatabasesTool.d.ts.map +1 -1
- package/dist/tools/ListDatabasesTool.js.map +1 -1
- package/package.json +5 -3
package/README.md
CHANGED
|
@@ -1,361 +1,329 @@
|
|
|
1
|
-
# MSSQL MCP Server
|
|
2
|
-
|
|
3
|
-
[](https://opensource.org/licenses/MIT)
|
|
4
|
-
[](https://www.npmjs.com/package/@eamonboyle/mssql-mcp)
|
|
5
|
-
[](https://nodejs.org/)
|
|
6
|
-
[](https://x.com/eamonyo)
|
|
7
|
-
|
|
8
|
-
[](https://cursor.com/en/install-mcp?name=
|
|
9
|
-
[](https://intradeus.github.io/http-protocol-redirector?r=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522mssql%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540eamonboyle%252Fmssql-mcp%2522%255D%252C%2522env%2522%253A%257B%2522SERVER_NAME%2522%253A%2522localhost%2522%252C%2522DATABASE_NAME%2522%253A%
|
|
10
|
-
|
|
11
|
-
>
|
|
12
|
-
|
|
13
|
-
##
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
-
|
|
34
|
-
-
|
|
35
|
-
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
-
|
|
307
|
-
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
| `update_data` | | Update rows (requires filters; optional `schemaName`) |
|
|
331
|
-
| `delete_data` | | Delete rows (requires filters; optional `schemaName`) |
|
|
332
|
-
| `create_table` | | Create tables (requires `ENABLE_DDL=true`) |
|
|
333
|
-
| `create_index` | | Create indexes (requires `ENABLE_DDL=true`) |
|
|
334
|
-
| `drop_table` | | Drop tables (requires `ENABLE_DDL=true`; optional `schemaName`) |
|
|
335
|
-
|
|
336
|
-
## Resources And Prompts
|
|
337
|
-
|
|
338
|
-
Clients that support MCP resources and prompts can use additional discovery surfaces:
|
|
339
|
-
|
|
340
|
-
- **Resources** — Server config, prompt catalog, per-database table lists, per-database object lists, and dynamic table/object resources
|
|
341
|
-
- **Prompts** — `explore_schema`, `draft_safe_select`, and `review_write_operation`
|
|
342
|
-
|
|
343
|
-
## Changelog
|
|
344
|
-
|
|
345
|
-
Release notes: [CHANGELOG.md](https://github.com/eamonboyle/mssql-mcp/blob/main/CHANGELOG.md).
|
|
346
|
-
|
|
347
|
-
## Security Notes
|
|
348
|
-
|
|
349
|
-
- **Credentials** — Never commit `DB_USER`/`DB_PASSWORD` or config files with secrets. Use environment variables or a secrets manager.
|
|
350
|
-
- **Read-only mode** — Set `READONLY: "true"` when you only need queries.
|
|
351
|
-
- **WHERE clauses** — Update and delete operations require explicit WHERE clauses to reduce accidental full-table changes.
|
|
352
|
-
- **SQL injection** — The server validates and restricts dangerous SQL patterns.
|
|
353
|
-
- **DDL tools** — Disabled by default (`ENABLE_DDL` unset or `false`). Set `ENABLE_DDL=true` only if the assistant should create/drop tables or indexes.
|
|
354
|
-
|
|
355
|
-
## Contributing
|
|
356
|
-
|
|
357
|
-
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. By participating, you agree to uphold our [Code of Conduct](CODE_OF_CONDUCT.md).
|
|
358
|
-
|
|
359
|
-
## License
|
|
360
|
-
|
|
361
|
-
MIT License — see [LICENSE](LICENSE) for details.
|
|
1
|
+
# MSSQL MCP Server
|
|
2
|
+
|
|
3
|
+
[](https://opensource.org/licenses/MIT)
|
|
4
|
+
[](https://www.npmjs.com/package/@eamonboyle/mssql-mcp)
|
|
5
|
+
[](https://nodejs.org/)
|
|
6
|
+
[](https://x.com/eamonyo)
|
|
7
|
+
|
|
8
|
+
[](https://cursor.com/en/install-mcp?name=mssql-local&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBlYW1vbmJveWxlL21zc3FsLW1jcCJdLCJlbnYiOnsiU0VSVkVSX05BTUUiOiJsb2NhbGhvc3QiLCJEQVRBQkFTRV9OQU1FIjoiQXBwREIiLCJEQVRBQkFTRVMiOiJBcHBEQixSZXBvcnRpbmdEQiIsIkRCX1VTRVIiOiJ5b3VyX3VzZXJuYW1lIiwiREJfUEFTU1dPUkQiOiJ5b3VyX3Bhc3N3b3JkIiwiVFJVU1RfU0VSVkVSX0NFUlRJRklDQVRFIjoidHJ1ZSIsIlJFQURPTkxZIjoiZmFsc2UiLCJFTkFCTEVfRERMIjoiZmFsc2UifX0=)
|
|
9
|
+
[](https://intradeus.github.io/http-protocol-redirector?r=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522mssql-local%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540eamonboyle%252Fmssql-mcp%2522%255D%252C%2522env%2522%253A%257B%2522SERVER_NAME%2522%253A%2522localhost%2522%252C%2522DATABASE_NAME%2522%253A%2522AppDB%2522%252C%2522DATABASES%2522%253A%2522AppDB%252CReportingDB%2522%252C%2522DB_USER%2522%253A%2522your_username%2522%252C%2522DB_PASSWORD%2522%253A%2522your_password%2522%252C%2522TRUST_SERVER_CERTIFICATE%2522%253A%2522true%2522%252C%2522READONLY%2522%253A%2522false%2522%252C%2522ENABLE_DDL%2522%253A%2522false%2522%257D%257D)
|
|
10
|
+
|
|
11
|
+
> Experimental use only. This server is intended for education and evaluation, not production. Use a dedicated least-privilege SQL login and test all operations.
|
|
12
|
+
|
|
13
|
+
## Overview
|
|
14
|
+
|
|
15
|
+
`@eamonboyle/mssql-mcp` exposes Microsoft SQL Server tools, resources, and prompts through the [Model Context Protocol](https://modelcontextprotocol.io/). The MCP client and its language model interpret natural-language requests and choose tools. This package validates requests, executes SQL Server operations, and returns structured results.
|
|
16
|
+
|
|
17
|
+
Key capabilities:
|
|
18
|
+
|
|
19
|
+
- Schema, object, relationship, dependency, and storage discovery
|
|
20
|
+
- Validated reads, parameterized searches, and estimated execution plans
|
|
21
|
+
- Insert, update, and delete tools with confirmation and row limits
|
|
22
|
+
- Preview tokens for update and delete operations
|
|
23
|
+
- DDL tools with an explicit configuration gate
|
|
24
|
+
- Multiple allowed databases on one SQL Server
|
|
25
|
+
- Local stdio and stateless Streamable HTTP transports
|
|
26
|
+
|
|
27
|
+
Supported clients include Cursor, VS Code, Claude Desktop, and other MCP-compatible hosts.
|
|
28
|
+
|
|
29
|
+
## Quick start
|
|
30
|
+
|
|
31
|
+
### Prerequisites
|
|
32
|
+
|
|
33
|
+
- Node.js 20 or newer
|
|
34
|
+
- Microsoft SQL Server
|
|
35
|
+
- An MCP-compatible client
|
|
36
|
+
|
|
37
|
+
The recommended installation runs the published package directly:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npx -y @eamonboyle/mssql-mcp
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
A global installation also exposes the `mssql-mcp` command:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npm install -g @eamonboyle/mssql-mcp
|
|
47
|
+
mssql-mcp
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The one-click links use the minimal configuration shown below. Replace the sample connection values before use.
|
|
51
|
+
|
|
52
|
+
The badge payloads are generated from `src/samples/claude_desktop_config.json`. After changing the sample, run `npm run docs:update-install-links`; use `npm run docs:check-install-links` to verify they are current.
|
|
53
|
+
|
|
54
|
+
## Minimal MCP configuration
|
|
55
|
+
|
|
56
|
+
The standard presets show connection placeholders and keep DDL disabled:
|
|
57
|
+
|
|
58
|
+
```json
|
|
59
|
+
{
|
|
60
|
+
"mcpServers": {
|
|
61
|
+
"mssql-local": {
|
|
62
|
+
"command": "npx",
|
|
63
|
+
"args": ["-y", "@eamonboyle/mssql-mcp"],
|
|
64
|
+
"env": {
|
|
65
|
+
"SERVER_NAME": "localhost",
|
|
66
|
+
"DATABASE_NAME": "AppDB",
|
|
67
|
+
"DATABASES": "AppDB,ReportingDB",
|
|
68
|
+
"DB_USER": "your_username",
|
|
69
|
+
"DB_PASSWORD": "your_password",
|
|
70
|
+
"TRUST_SERVER_CERTIFICATE": "true",
|
|
71
|
+
"READONLY": "false",
|
|
72
|
+
"ENABLE_DDL": "false"
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Cursor uses `mcpServers` in `~/.cursor/mcp.json` or `.cursor/mcp.json`. Claude Desktop uses the same shape in its configuration file.
|
|
80
|
+
|
|
81
|
+
Set `ENABLE_DDL=true` only when the assistant specifically needs to create or remove schema objects.
|
|
82
|
+
|
|
83
|
+
VS Code uses `.vscode/mcp.json` or its user MCP configuration with a top-level `servers` object:
|
|
84
|
+
|
|
85
|
+
```json
|
|
86
|
+
{
|
|
87
|
+
"servers": {
|
|
88
|
+
"mssql-local": {
|
|
89
|
+
"type": "stdio",
|
|
90
|
+
"command": "npx",
|
|
91
|
+
"args": ["-y", "@eamonboyle/mssql-mcp"],
|
|
92
|
+
"env": {
|
|
93
|
+
"SERVER_NAME": "localhost",
|
|
94
|
+
"DATABASE_NAME": "AppDB",
|
|
95
|
+
"DATABASES": "AppDB,ReportingDB",
|
|
96
|
+
"DB_USER": "your_username",
|
|
97
|
+
"DB_PASSWORD": "your_password",
|
|
98
|
+
"TRUST_SERVER_CERTIFICATE": "true",
|
|
99
|
+
"READONLY": "false",
|
|
100
|
+
"ENABLE_DDL": "false"
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
See [`src/samples/`](src/samples/) for copyable Claude Desktop and VS Code files. Do not commit configuration files containing real credentials.
|
|
108
|
+
|
|
109
|
+
## Required configuration
|
|
110
|
+
|
|
111
|
+
The server validates these variables before starting. Missing or blank values produce an actionable startup error.
|
|
112
|
+
|
|
113
|
+
| Variable | Accepted format | Purpose |
|
|
114
|
+
| -------------------------- | ---------------------- | --------------------------------------------------------------------- |
|
|
115
|
+
| `DB_USER` | Nonblank string | SQL authentication username |
|
|
116
|
+
| `DB_PASSWORD` | Nonblank string | SQL authentication password |
|
|
117
|
+
|
|
118
|
+
At least one database variable is required: set `DATABASE_NAME`, `DATABASES`, or both. With only `DATABASE_NAME`, that database is both the default and the allowlist. With only `DATABASES`, the first entry is the default. When both are set, `DATABASE_NAME` is used if it appears in `DATABASES`; otherwise the first allowed database is the runtime default.
|
|
119
|
+
|
|
120
|
+
### Hostname and port
|
|
121
|
+
|
|
122
|
+
> Do not include the port in `SERVER_NAME`. Values such as `localhost,1434` are not supported by the Node.js `mssql` driver configuration used by this package. Set `SERVER_NAME` to the hostname and use `SERVER_PORT` separately.
|
|
123
|
+
|
|
124
|
+
```json
|
|
125
|
+
{
|
|
126
|
+
"SERVER_NAME": "localhost",
|
|
127
|
+
"SERVER_PORT": "1434"
|
|
128
|
+
}
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
For a Docker port mapping such as:
|
|
132
|
+
|
|
133
|
+
```yaml
|
|
134
|
+
ports:
|
|
135
|
+
- "1434:1433"
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
use the published host port:
|
|
139
|
+
|
|
140
|
+
```text
|
|
141
|
+
SERVER_NAME=localhost
|
|
142
|
+
SERVER_PORT=1434
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
The container still listens on `1433`, but the MCP process connects through host port `1434`.
|
|
146
|
+
|
|
147
|
+
## Advanced configuration
|
|
148
|
+
|
|
149
|
+
Optional variables do not need empty placeholders. In-code defaults apply when they are absent.
|
|
150
|
+
|
|
151
|
+
| Variable | Accepted format | Default | Purpose |
|
|
152
|
+
| ----------------------- | ----------------------------- | --------------------- | -------------------------------------------------------------- |
|
|
153
|
+
| `SERVER_NAME` | Hostname | `localhost` | SQL Server hostname only |
|
|
154
|
+
| `SERVER_PORT` | Integer from `1` to `65535` | Driver default `1433` | SQL Server TCP port; omitted from the driver config when unset |
|
|
155
|
+
| `ENCRYPT` | `"true"` or `"false"` | `"false"` | Enable TLS encryption in the `mssql` driver |
|
|
156
|
+
| `TRUST_SERVER_CERTIFICATE` | `"true"` or `"false"` | `"true"` | Trust the SQL Server certificate without validating its chain |
|
|
157
|
+
| `READONLY` | `"true"` or `"false"` | `"false"` | Remove write and DDL tools when enabled |
|
|
158
|
+
| `ENABLE_DDL` | `"true"` or `"false"` | `"false"` | Allow registered DDL tools to execute |
|
|
159
|
+
| `CONNECTION_TIMEOUT` | Positive integer seconds | `30` | SQL Server connection timeout |
|
|
160
|
+
| `QUERY_TIMEOUT_MS` | Positive integer milliseconds | `30000` | SQL request timeout |
|
|
161
|
+
| `MAX_ROWS` | Positive integer | `10000` | Maximum rows returned by read tools |
|
|
162
|
+
| `MAX_WRITE_ROWS` | Positive integer | `100` | Maximum rows one write operation may affect |
|
|
163
|
+
| `REQUIRE_WRITE_PREVIEW` | `"true"` or `"false"` | `"true"` | Require a matching preview token for updates and deletes |
|
|
164
|
+
| `MCP_TRANSPORT` | `stdio` or `http` | `stdio` | MCP transport mode |
|
|
165
|
+
| `MCP_HTTP_HOST` | Host or IP string | `127.0.0.1` | Bind address for HTTP mode |
|
|
166
|
+
| `MCP_HTTP_PORT` | Integer from `1` to `65535` | `3333` | Bind port for HTTP mode |
|
|
167
|
+
| `MCP_BASE_URL` | Absolute HTTP or HTTPS URL | Unset | Public HTTP base advertised by the server; `/mcp` is appended |
|
|
168
|
+
|
|
169
|
+
Blank optional values use their documented defaults. Explicit nonblank invalid integers, booleans, ports, URLs, or transport names fail validation rather than falling back silently.
|
|
170
|
+
|
|
171
|
+
`ENCRYPT=false` preserves the existing unencrypted connection behavior. Set `ENCRYPT=true` for TLS. With encryption enabled, keep `TRUST_SERVER_CERTIFICATE=false` for certificates that chain to a trusted authority. Use `TRUST_SERVER_CERTIFICATE=true` only when explicitly accepting a self-signed or otherwise untrusted certificate, such as local development.
|
|
172
|
+
|
|
173
|
+
## Multi-database behavior
|
|
174
|
+
|
|
175
|
+
`DATABASES` is an allowlist. Every tool accepts an optional `databaseName`. When a tool omits it, the server uses `DATABASE_NAME` if that name is allowed, otherwise it uses the first entry in `DATABASES`. A requested database outside the allowlist is rejected.
|
|
176
|
+
|
|
177
|
+
## Safe writes and DDL
|
|
178
|
+
|
|
179
|
+
`READONLY=true` removes insert, update, delete, and DDL tools. Read-only preview tools remain available because they do not modify data.
|
|
180
|
+
|
|
181
|
+
When writes are enabled:
|
|
182
|
+
|
|
183
|
+
1. `insert_data`, `update_data`, `delete_data`, and DDL tools require `confirmed: true` unless the client completes MCP elicitation.
|
|
184
|
+
2. `update_data` and `delete_data` require nonempty structured `filters`, not raw SQL WHERE text.
|
|
185
|
+
3. With the default `REQUIRE_WRITE_PREVIEW=true`, call `preview_update` or `preview_delete` first and pass its `previewToken` to the matching write.
|
|
186
|
+
4. Preview tokens expire after 10 minutes, are single-use, and are bound to the same tool, table, filters, and update payload.
|
|
187
|
+
5. `MAX_WRITE_ROWS` rejects oversized operations, and update/delete execution applies a row cap.
|
|
188
|
+
|
|
189
|
+
Supported filter operators are `=`, `!=`, `>`, `>=`, `<`, `<=`, `LIKE`, `IN`, `IS NULL`, and `IS NOT NULL`.
|
|
190
|
+
|
|
191
|
+
DDL tools are registered when `READONLY=false`, but calls fail with `DDL_DISABLED` unless `ENABLE_DDL=true`.
|
|
192
|
+
|
|
193
|
+
For `insert_data`, pass the table in `tableName` and the schema separately in `schemaName`. Do not use a dotted `schema.table` value for `tableName`.
|
|
194
|
+
|
|
195
|
+
## Streamable HTTP
|
|
196
|
+
|
|
197
|
+
The default transport is stdio. To run the stateless HTTP transport from a directory containing a configured `.env`:
|
|
198
|
+
|
|
199
|
+
```bash
|
|
200
|
+
MCP_TRANSPORT=http npx -y @eamonboyle/mssql-mcp
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
The default endpoint is:
|
|
204
|
+
|
|
205
|
+
```text
|
|
206
|
+
http://127.0.0.1:3333/mcp
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
An HTTP client must accept `application/json, text/event-stream`. Each HTTP request creates a fresh MCP server instance. Preview tokens use a process-wide store so they remain valid across requests to the same process.
|
|
210
|
+
|
|
211
|
+
For a reverse proxy or externally published path, set `MCP_BASE_URL` to the public base without the final `/mcp` segment:
|
|
212
|
+
|
|
213
|
+
```text
|
|
214
|
+
MCP_BASE_URL=https://example.com/services/mssql
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
The server continues binding to `MCP_HTTP_HOST:MCP_HTTP_PORT`, logs `https://example.com/services/mssql/mcp` as its public endpoint, and exposes that URL through `mssql://config/server`. `MCP_E2E_BASE_URL` is a separate test-harness variable used only by `scripts/e2e-mcp-tools.mjs`.
|
|
218
|
+
|
|
219
|
+
Cursor HTTP configuration:
|
|
220
|
+
|
|
221
|
+
```json
|
|
222
|
+
{
|
|
223
|
+
"mcpServers": {
|
|
224
|
+
"mssql-http": {
|
|
225
|
+
"url": "http://127.0.0.1:3333/mcp"
|
|
226
|
+
}
|
|
227
|
+
}
|
|
228
|
+
}
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
## Tools
|
|
232
|
+
|
|
233
|
+
| Tool | Mode | Purpose |
|
|
234
|
+
| ------------------------ | ----- | ---------------------------------------------------------------- |
|
|
235
|
+
| `list_databases` | Read | List configured databases |
|
|
236
|
+
| `list_table` | Read | List tables, optionally filtered by schema names in `parameters` |
|
|
237
|
+
| `describe_table` | Read | Describe a table schema |
|
|
238
|
+
| `list_objects` | Read | List tables, views, procedures, functions, and triggers |
|
|
239
|
+
| `describe_object` | Read | Return object metadata and definitions |
|
|
240
|
+
| `summarize_schema` | Read | Summarize object counts by type and schema |
|
|
241
|
+
| `list_largest_tables` | Read | Rank tables by storage and row count |
|
|
242
|
+
| `list_foreign_keys` | Read | List foreign keys |
|
|
243
|
+
| `describe_relationships` | Read | Describe foreign keys involving one table |
|
|
244
|
+
| `describe_dependencies` | Read | List objects that depend on an object |
|
|
245
|
+
| `analyze_table` | Read | Return row counts, storage, and index details |
|
|
246
|
+
| `read_data` | Read | Execute a validated SELECT query |
|
|
247
|
+
| `search_data` | Read | Search columns with parameterized LIKE predicates |
|
|
248
|
+
| `explain_query` | Read | Generate an estimated SELECT execution plan |
|
|
249
|
+
| `preview_update` | Read | Preview an update and issue a token when required |
|
|
250
|
+
| `preview_delete` | Read | Preview a delete and issue a token when required |
|
|
251
|
+
| `insert_data` | Write | Insert rows |
|
|
252
|
+
| `update_data` | Write | Update rows selected by structured filters |
|
|
253
|
+
| `delete_data` | Write | Delete rows selected by structured filters |
|
|
254
|
+
| `create_table` | DDL | Create a table |
|
|
255
|
+
| `create_index` | DDL | Create an index |
|
|
256
|
+
| `drop_table` | DDL | Drop a table |
|
|
257
|
+
|
|
258
|
+
## Resources and prompts
|
|
259
|
+
|
|
260
|
+
Clients with MCP resource support can discover:
|
|
261
|
+
|
|
262
|
+
- `mssql://config/server`
|
|
263
|
+
- `mssql://config/prompts`
|
|
264
|
+
- `mssql://database/{databaseName}/tables`
|
|
265
|
+
- `mssql://database/{databaseName}/objects`
|
|
266
|
+
- `mssql://database/{databaseName}/schema-summary`
|
|
267
|
+
- `mssql://database/{databaseName}/foreign-keys`
|
|
268
|
+
- `mssql://table/{databaseName}/{schemaName}/{tableName}`
|
|
269
|
+
- `mssql://object/{databaseName}/{schemaName}/{objectName}`
|
|
270
|
+
- `mssql://database/{databaseName}/object/{schemaName}/{objectName}/dependencies`
|
|
271
|
+
- `mssql://query-plan/{planId}`
|
|
272
|
+
- `mssql://query-result/{resultId}`
|
|
273
|
+
|
|
274
|
+
Table and object listings are cached for 30 seconds. Query plan and large query result resources are temporary process-local artifacts.
|
|
275
|
+
|
|
276
|
+
Available prompts:
|
|
277
|
+
|
|
278
|
+
- `explore_schema`
|
|
279
|
+
- `draft_safe_select`
|
|
280
|
+
- `review_write_operation`
|
|
281
|
+
|
|
282
|
+
## Development
|
|
283
|
+
|
|
284
|
+
For local source development only:
|
|
285
|
+
|
|
286
|
+
```bash
|
|
287
|
+
git clone https://github.com/eamonboyle/mssql-mcp.git
|
|
288
|
+
cd mssql-mcp
|
|
289
|
+
npm install
|
|
290
|
+
npm run build
|
|
291
|
+
node /path/to/mssql-mcp/dist/index.js
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
The repository includes a seeded SQL Server 2022 Docker environment:
|
|
295
|
+
|
|
296
|
+
```bash
|
|
297
|
+
cp .env.example .env
|
|
298
|
+
npm run db:up
|
|
299
|
+
npm run test:e2e
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
See [`docs/dev-database.md`](docs/dev-database.md) for database and E2E details and [`CONTRIBUTING.md`](CONTRIBUTING.md) for build, lint, and test commands.
|
|
303
|
+
|
|
304
|
+
## Troubleshooting
|
|
305
|
+
|
|
306
|
+
- `SERVER_PORT must be a valid TCP port`: use a whole number from `1` to `65535`.
|
|
307
|
+
- `getaddrinfo ENOTFOUND localhost,1434`: move `1434` from `SERVER_NAME` to `SERVER_PORT`.
|
|
308
|
+
- `DDL_DISABLED`: set `ENABLE_DDL` to `"true"` only when DDL access is intended.
|
|
309
|
+
- `PREVIEW_TOKEN_INVALID`: create a new matching preview and use its token once within 10 minutes.
|
|
310
|
+
- stdio JSON parse errors: ensure scripts and dependencies write logs to stderr, not stdout.
|
|
311
|
+
- database rejected: add it to `DATABASES` and use the exact allowed name in `databaseName`.
|
|
312
|
+
|
|
313
|
+
## Security
|
|
314
|
+
|
|
315
|
+
- Use a dedicated SQL login with the minimum permissions required.
|
|
316
|
+
- Set `READONLY=true` whenever writes are unnecessary.
|
|
317
|
+
- Keep `ENABLE_DDL=false` unless schema changes are explicitly needed.
|
|
318
|
+
- Keep credentials out of source control and use your client's secret-input support or a secrets manager.
|
|
319
|
+
- Bind HTTP mode to a trusted interface and add network authentication or isolation outside this package.
|
|
320
|
+
- Set `ENCRYPT=true` for TLS deployments and keep `TRUST_SERVER_CERTIFICATE=false` when the server certificate is publicly or privately trusted.
|
|
321
|
+
- Report vulnerabilities through the [security policy](.github/SECURITY.md).
|
|
322
|
+
|
|
323
|
+
## Project links
|
|
324
|
+
|
|
325
|
+
- [Changelog](CHANGELOG.md)
|
|
326
|
+
- [Contributing](CONTRIBUTING.md)
|
|
327
|
+
- [Code of Conduct](CODE_OF_CONDUCT.md)
|
|
328
|
+
- [Security Policy](.github/SECURITY.md)
|
|
329
|
+
- [License](LICENSE)
|