nife-restapi-mcp-server 1.0.0__tar.gz
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.
- nife_restapi_mcp_server-1.0.0/LICENSE +21 -0
- nife_restapi_mcp_server-1.0.0/PKG-INFO +349 -0
- nife_restapi_mcp_server-1.0.0/README.md +296 -0
- nife_restapi_mcp_server-1.0.0/pyproject.toml +50 -0
- nife_restapi_mcp_server-1.0.0/setup.cfg +4 -0
- nife_restapi_mcp_server-1.0.0/src/nife_restapi_mcp_server.egg-info/PKG-INFO +349 -0
- nife_restapi_mcp_server-1.0.0/src/nife_restapi_mcp_server.egg-info/SOURCES.txt +14 -0
- nife_restapi_mcp_server-1.0.0/src/nife_restapi_mcp_server.egg-info/dependency_links.txt +1 -0
- nife_restapi_mcp_server-1.0.0/src/nife_restapi_mcp_server.egg-info/entry_points.txt +2 -0
- nife_restapi_mcp_server-1.0.0/src/nife_restapi_mcp_server.egg-info/requires.txt +13 -0
- nife_restapi_mcp_server-1.0.0/src/nife_restapi_mcp_server.egg-info/top_level.txt +1 -0
- nife_restapi_mcp_server-1.0.0/src/restapi_mcp_server/__init__.py +13 -0
- nife_restapi_mcp_server-1.0.0/src/restapi_mcp_server/__main__.py +178 -0
- nife_restapi_mcp_server-1.0.0/src/restapi_mcp_server/rest_client.py +220 -0
- nife_restapi_mcp_server-1.0.0/src/restapi_mcp_server/schema_manager.py +289 -0
- nife_restapi_mcp_server-1.0.0/src/restapi_mcp_server/server.py +894 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 REST API MCP Server Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,349 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: nife-restapi-mcp-server
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Dynamic MCP server that auto-generates tools from any REST API OpenAPI/Swagger schema
|
|
5
|
+
Author-email: Varun S <varun@nife.io>
|
|
6
|
+
License: MIT License
|
|
7
|
+
|
|
8
|
+
Copyright (c) 2024 REST API MCP Server Contributors
|
|
9
|
+
|
|
10
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
11
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
12
|
+
in the Software without restriction, including without limitation the rights
|
|
13
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
14
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
15
|
+
furnished to do so, subject to the following conditions:
|
|
16
|
+
|
|
17
|
+
The above copyright notice and this permission notice shall be included in all
|
|
18
|
+
copies or substantial portions of the Software.
|
|
19
|
+
|
|
20
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
21
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
22
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
23
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
24
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
25
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
26
|
+
SOFTWARE.
|
|
27
|
+
|
|
28
|
+
Project-URL: Repository, https://github.com/nifetency/nife-mcp-restapi
|
|
29
|
+
Keywords: mcp,restapi,openapi,swagger,llm,claude,ai,model-context-protocol
|
|
30
|
+
Classifier: Programming Language :: Python :: 3
|
|
31
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
32
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
33
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
34
|
+
Classifier: Operating System :: OS Independent
|
|
35
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
36
|
+
Classifier: Intended Audience :: Developers
|
|
37
|
+
Requires-Python: >=3.11
|
|
38
|
+
Description-Content-Type: text/markdown
|
|
39
|
+
License-File: LICENSE
|
|
40
|
+
Requires-Dist: requests>=2.31.0
|
|
41
|
+
Requires-Dist: python-dotenv>=1.0.0
|
|
42
|
+
Requires-Dist: pyyaml>=6.0.1
|
|
43
|
+
Requires-Dist: aiohttp>=3.9.0
|
|
44
|
+
Requires-Dist: python-json-logger>=2.0.7
|
|
45
|
+
Provides-Extra: dev
|
|
46
|
+
Requires-Dist: pytest>=7.4.0; extra == "dev"
|
|
47
|
+
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
|
|
48
|
+
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
|
|
49
|
+
Requires-Dist: mypy>=1.7.0; extra == "dev"
|
|
50
|
+
Requires-Dist: types-requests>=2.31.0; extra == "dev"
|
|
51
|
+
Requires-Dist: types-pyyaml>=6.0.12; extra == "dev"
|
|
52
|
+
Dynamic: license-file
|
|
53
|
+
|
|
54
|
+
# REST API MCP Server
|
|
55
|
+
|
|
56
|
+

|
|
57
|
+

|
|
58
|
+

|
|
59
|
+
|
|
60
|
+
A dynamic Model Context Protocol (MCP) server that automatically discovers and generates tools from any REST API using OpenAPI/Swagger specifications. Point it at any OpenAPI spec and it instantly exposes every endpoint as an MCP tool — zero manual configuration.
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## Installation
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
pip install restapi-mcp-server
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## Configuration
|
|
73
|
+
|
|
74
|
+
There are **four ways** to configure the server. They are applied in priority order — higher entries win:
|
|
75
|
+
|
|
76
|
+
| Priority | Method | Best for |
|
|
77
|
+
|----------|--------|----------|
|
|
78
|
+
| 1 | CLI arguments | One-off runs, testing |
|
|
79
|
+
| 2 | Environment variables | Docker, CI/CD, shell scripts |
|
|
80
|
+
| 3 | `.env` file | Local development |
|
|
81
|
+
| 4 | Defaults | Nothing required by default |
|
|
82
|
+
|
|
83
|
+
### Method 1 — CLI Arguments
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
restapi-mcp-server --base-url https://api.example.com --spec-url https://api.example.com/openapi.json --token mytoken
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
All available flags:
|
|
90
|
+
|
|
91
|
+
```
|
|
92
|
+
--base-url URL REST API base URL (required if not set via env)
|
|
93
|
+
--spec-url URL OpenAPI/Swagger spec URL or local file path (required if not set via env)
|
|
94
|
+
--token TOKEN API access token for bearer authentication
|
|
95
|
+
--auth-type TYPE Authentication type: bearer, apikey, basic, none (default: bearer)
|
|
96
|
+
--mode stdio|http Server mode (default: stdio)
|
|
97
|
+
--port PORT HTTP port, only used in http mode (default: 8080)
|
|
98
|
+
--host HOST HTTP host, only used in http mode (default: 0.0.0.0)
|
|
99
|
+
--log-level LEVEL Logging level: DEBUG, INFO, WARNING, ERROR (default: INFO)
|
|
100
|
+
--env-file PATH Path to a custom .env file
|
|
101
|
+
--version Show version and exit
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### Method 2 — Environment Variables
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
export REST_API_BASE_URL=https://api.example.com
|
|
108
|
+
export OPENAPI_SPEC_URL=https://api.example.com/openapi.json
|
|
109
|
+
export API_ACCESS_TOKEN=your_token_here
|
|
110
|
+
export MCP_MODE=stdio
|
|
111
|
+
|
|
112
|
+
restapi-mcp-server
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### Method 3 — `.env` File
|
|
116
|
+
|
|
117
|
+
Create a `.env` file in your working directory:
|
|
118
|
+
|
|
119
|
+
```env
|
|
120
|
+
REST_API_BASE_URL=https://api.example.com
|
|
121
|
+
OPENAPI_SPEC_URL=https://api.example.com/openapi.json
|
|
122
|
+
API_ACCESS_TOKEN=your_token_here
|
|
123
|
+
AUTH_TYPE=bearer
|
|
124
|
+
MCP_MODE=stdio
|
|
125
|
+
LOG_LEVEL=INFO
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Then just run:
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
restapi-mcp-server
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### Method 4 — Claude Desktop Config (most common for MCP use)
|
|
135
|
+
|
|
136
|
+
No `.env` file needed. Pass everything via the `env` block in `claude_desktop_config.json`:
|
|
137
|
+
|
|
138
|
+
```json
|
|
139
|
+
{
|
|
140
|
+
"mcpServers": {
|
|
141
|
+
"restapi": {
|
|
142
|
+
"command": "restapi-mcp-server",
|
|
143
|
+
"env": {
|
|
144
|
+
"REST_API_BASE_URL": "https://api.example.com",
|
|
145
|
+
"OPENAPI_SPEC_URL": "https://api.example.com/openapi.json",
|
|
146
|
+
"API_ACCESS_TOKEN": "your_token_here",
|
|
147
|
+
"MCP_MODE": "stdio",
|
|
148
|
+
"ENABLE_HTTP_ENDPOINT": "false"
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Claude Desktop injects the `env` block values directly into the process — this is the standard MCP pattern.
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## Environment Variable Reference
|
|
160
|
+
|
|
161
|
+
| Variable | Required | Default | Description |
|
|
162
|
+
|----------|----------|---------|-------------|
|
|
163
|
+
| `REST_API_BASE_URL` | Yes | — | REST API base URL |
|
|
164
|
+
| `OPENAPI_SPEC_URL` | Yes | — | OpenAPI/Swagger spec URL or local file path |
|
|
165
|
+
| `AUTH_TYPE` | No | `bearer` | Auth method: `bearer`, `apikey`, `basic`, `none` |
|
|
166
|
+
| `API_ACCESS_TOKEN` | No | — | Bearer token for auth |
|
|
167
|
+
| `API_KEY_HEADER` | No | `X-API-Key` | Header name for API key auth |
|
|
168
|
+
| `API_KEY_VALUE` | No | — | API key value |
|
|
169
|
+
| `BASIC_AUTH_USERNAME` | No | — | Username for basic auth |
|
|
170
|
+
| `BASIC_AUTH_PASSWORD` | No | — | Password for basic auth |
|
|
171
|
+
| `MCP_MODE` | No | `stdio` | `stdio` or `http` |
|
|
172
|
+
| `ENABLE_HTTP_ENDPOINT` | No | `true` | Enable HTTP health/metrics endpoints |
|
|
173
|
+
| `MCP_SERVER_PORT` | No | `8080` | HTTP server port |
|
|
174
|
+
| `MCP_SERVER_HOST` | No | `0.0.0.0` | HTTP server host |
|
|
175
|
+
| `LOG_LEVEL` | No | `INFO` | Logging verbosity |
|
|
176
|
+
| `REQUEST_TIMEOUT` | No | `30` | Request timeout in seconds |
|
|
177
|
+
| `SCHEMA_CACHE_TTL` | No | `3600` | Schema cache TTL in seconds |
|
|
178
|
+
|
|
179
|
+
---
|
|
180
|
+
|
|
181
|
+
## Operating Modes
|
|
182
|
+
|
|
183
|
+
### MCP Mode (`stdio`) — for Claude Desktop, Cursor, MCP clients
|
|
184
|
+
|
|
185
|
+
```bash
|
|
186
|
+
restapi-mcp-server --base-url https://api.example.com --spec-url https://api.example.com/openapi.json --mode stdio
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Communicates via stdin/stdout. No HTTP server is started. This is the default.
|
|
190
|
+
|
|
191
|
+
### HTTP Mode — for Docker, Kubernetes, server deployments
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
restapi-mcp-server --base-url https://api.example.com --spec-url https://api.example.com/openapi.json --mode http --port 8080
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
Starts an HTTP server with health and metrics endpoints:
|
|
198
|
+
- `GET /` — server info
|
|
199
|
+
- `GET /health` — health check
|
|
200
|
+
- `GET /metrics` — server metrics
|
|
201
|
+
- `GET /schema` — OpenAPI schema summary
|
|
202
|
+
- `GET /tools` — all generated tools
|
|
203
|
+
- `GET /api/endpoints` — all API endpoints
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## Authentication Methods
|
|
208
|
+
|
|
209
|
+
### Bearer Token
|
|
210
|
+
|
|
211
|
+
```env
|
|
212
|
+
AUTH_TYPE=bearer
|
|
213
|
+
API_ACCESS_TOKEN=your_token
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
### API Key
|
|
217
|
+
|
|
218
|
+
```env
|
|
219
|
+
AUTH_TYPE=apikey
|
|
220
|
+
API_KEY_HEADER=X-API-Key
|
|
221
|
+
API_KEY_VALUE=your_key
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
### Basic Authentication
|
|
225
|
+
|
|
226
|
+
```env
|
|
227
|
+
AUTH_TYPE=basic
|
|
228
|
+
BASIC_AUTH_USERNAME=username
|
|
229
|
+
BASIC_AUTH_PASSWORD=password
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
### No Authentication
|
|
233
|
+
|
|
234
|
+
```env
|
|
235
|
+
AUTH_TYPE=none
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
---
|
|
239
|
+
|
|
240
|
+
## Docker
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
docker build -t restapi-mcp-server .
|
|
244
|
+
|
|
245
|
+
docker run -p 8080:8080 \
|
|
246
|
+
-e REST_API_BASE_URL=https://api.example.com \
|
|
247
|
+
-e OPENAPI_SPEC_URL=https://api.example.com/openapi.json \
|
|
248
|
+
-e API_ACCESS_TOKEN=your_token \
|
|
249
|
+
-e MCP_MODE=http \
|
|
250
|
+
restapi-mcp-server
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
Or with Docker Compose:
|
|
254
|
+
|
|
255
|
+
```bash
|
|
256
|
+
cp .env.example .env # fill in your values
|
|
257
|
+
docker-compose up
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
---
|
|
261
|
+
|
|
262
|
+
## Available Tools
|
|
263
|
+
|
|
264
|
+
The server dynamically generates the following tool types:
|
|
265
|
+
|
|
266
|
+
### Endpoint Tools
|
|
267
|
+
Named by HTTP method and path: `<method>_<path_parts>`
|
|
268
|
+
|
|
269
|
+
Examples:
|
|
270
|
+
- `get_users`
|
|
271
|
+
- `post_users`
|
|
272
|
+
- `get_users_by_id`
|
|
273
|
+
- `delete_users_by_id`
|
|
274
|
+
- `put_users_by_id`
|
|
275
|
+
|
|
276
|
+
### Utility Tools
|
|
277
|
+
- `list_available_endpoints` — list all endpoints (filterable by method or path)
|
|
278
|
+
- `get_endpoint_info` — detailed info about a specific endpoint
|
|
279
|
+
- `get_schema_info` — OpenAPI schema summary or specific model details
|
|
280
|
+
- `execute_custom_request` — run any HTTP request with full control
|
|
281
|
+
- `health_check` — server health and schema status
|
|
282
|
+
|
|
283
|
+
---
|
|
284
|
+
|
|
285
|
+
## OpenAPI Specification Support
|
|
286
|
+
|
|
287
|
+
- OpenAPI 3.x (full support)
|
|
288
|
+
- Swagger 2.0 (backward compatible)
|
|
289
|
+
|
|
290
|
+
Supported spec sources:
|
|
291
|
+
- Remote JSON URL
|
|
292
|
+
- Remote YAML URL
|
|
293
|
+
- Local JSON file
|
|
294
|
+
- Local YAML file
|
|
295
|
+
|
|
296
|
+
---
|
|
297
|
+
|
|
298
|
+
## Key Features
|
|
299
|
+
|
|
300
|
+
- **Zero config endpoints** — auto-parses any OpenAPI/Swagger spec and generates MCP tools
|
|
301
|
+
- **Dual mode** — stdio for MCP clients, HTTP for server deployments
|
|
302
|
+
- **Flexible config** — CLI args, env vars, .env file, or Claude Desktop env block
|
|
303
|
+
- **Multiple auth methods** — Bearer, API key, Basic, or none
|
|
304
|
+
- **Production ready** — Docker, Kubernetes, AWS ECS, Google Cloud Run compatible
|
|
305
|
+
- **Self-documenting** — `list_available_endpoints`, `get_endpoint_info`, `get_schema_info` tools built in
|
|
306
|
+
|
|
307
|
+
---
|
|
308
|
+
|
|
309
|
+
## Troubleshooting
|
|
310
|
+
|
|
311
|
+
**`[ERROR] REST API base URL not configured`**
|
|
312
|
+
|
|
313
|
+
Set `REST_API_BASE_URL` via any method above. The most common fix:
|
|
314
|
+
```bash
|
|
315
|
+
restapi-mcp-server --base-url https://your-api.com
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
**`[ERROR] OpenAPI spec URL not configured`**
|
|
319
|
+
|
|
320
|
+
Set `OPENAPI_SPEC_URL` via any method above:
|
|
321
|
+
```bash
|
|
322
|
+
restapi-mcp-server --spec-url https://your-api.com/openapi.json
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
**Port already in use**
|
|
326
|
+
|
|
327
|
+
Change the port:
|
|
328
|
+
```bash
|
|
329
|
+
restapi-mcp-server --mode http --port 9090
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
**Docker container exits immediately**
|
|
333
|
+
|
|
334
|
+
Make sure you're using HTTP mode:
|
|
335
|
+
```bash
|
|
336
|
+
docker run -e MCP_MODE=http -e REST_API_BASE_URL=... -e OPENAPI_SPEC_URL=... restapi-mcp-server
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
**Schema not loading**
|
|
340
|
+
|
|
341
|
+
- Verify the spec URL is reachable
|
|
342
|
+
- Check the format is valid JSON or YAML
|
|
343
|
+
- Ensure the spec is OpenAPI 3.x or Swagger 2.0
|
|
344
|
+
|
|
345
|
+
---
|
|
346
|
+
|
|
347
|
+
## License
|
|
348
|
+
|
|
349
|
+
MIT
|
|
@@ -0,0 +1,296 @@
|
|
|
1
|
+
# REST API MCP Server
|
|
2
|
+
|
|
3
|
+

|
|
4
|
+

|
|
5
|
+

|
|
6
|
+
|
|
7
|
+
A dynamic Model Context Protocol (MCP) server that automatically discovers and generates tools from any REST API using OpenAPI/Swagger specifications. Point it at any OpenAPI spec and it instantly exposes every endpoint as an MCP tool — zero manual configuration.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Installation
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
pip install restapi-mcp-server
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Configuration
|
|
20
|
+
|
|
21
|
+
There are **four ways** to configure the server. They are applied in priority order — higher entries win:
|
|
22
|
+
|
|
23
|
+
| Priority | Method | Best for |
|
|
24
|
+
|----------|--------|----------|
|
|
25
|
+
| 1 | CLI arguments | One-off runs, testing |
|
|
26
|
+
| 2 | Environment variables | Docker, CI/CD, shell scripts |
|
|
27
|
+
| 3 | `.env` file | Local development |
|
|
28
|
+
| 4 | Defaults | Nothing required by default |
|
|
29
|
+
|
|
30
|
+
### Method 1 — CLI Arguments
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
restapi-mcp-server --base-url https://api.example.com --spec-url https://api.example.com/openapi.json --token mytoken
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
All available flags:
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
--base-url URL REST API base URL (required if not set via env)
|
|
40
|
+
--spec-url URL OpenAPI/Swagger spec URL or local file path (required if not set via env)
|
|
41
|
+
--token TOKEN API access token for bearer authentication
|
|
42
|
+
--auth-type TYPE Authentication type: bearer, apikey, basic, none (default: bearer)
|
|
43
|
+
--mode stdio|http Server mode (default: stdio)
|
|
44
|
+
--port PORT HTTP port, only used in http mode (default: 8080)
|
|
45
|
+
--host HOST HTTP host, only used in http mode (default: 0.0.0.0)
|
|
46
|
+
--log-level LEVEL Logging level: DEBUG, INFO, WARNING, ERROR (default: INFO)
|
|
47
|
+
--env-file PATH Path to a custom .env file
|
|
48
|
+
--version Show version and exit
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### Method 2 — Environment Variables
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
export REST_API_BASE_URL=https://api.example.com
|
|
55
|
+
export OPENAPI_SPEC_URL=https://api.example.com/openapi.json
|
|
56
|
+
export API_ACCESS_TOKEN=your_token_here
|
|
57
|
+
export MCP_MODE=stdio
|
|
58
|
+
|
|
59
|
+
restapi-mcp-server
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### Method 3 — `.env` File
|
|
63
|
+
|
|
64
|
+
Create a `.env` file in your working directory:
|
|
65
|
+
|
|
66
|
+
```env
|
|
67
|
+
REST_API_BASE_URL=https://api.example.com
|
|
68
|
+
OPENAPI_SPEC_URL=https://api.example.com/openapi.json
|
|
69
|
+
API_ACCESS_TOKEN=your_token_here
|
|
70
|
+
AUTH_TYPE=bearer
|
|
71
|
+
MCP_MODE=stdio
|
|
72
|
+
LOG_LEVEL=INFO
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Then just run:
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
restapi-mcp-server
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### Method 4 — Claude Desktop Config (most common for MCP use)
|
|
82
|
+
|
|
83
|
+
No `.env` file needed. Pass everything via the `env` block in `claude_desktop_config.json`:
|
|
84
|
+
|
|
85
|
+
```json
|
|
86
|
+
{
|
|
87
|
+
"mcpServers": {
|
|
88
|
+
"restapi": {
|
|
89
|
+
"command": "restapi-mcp-server",
|
|
90
|
+
"env": {
|
|
91
|
+
"REST_API_BASE_URL": "https://api.example.com",
|
|
92
|
+
"OPENAPI_SPEC_URL": "https://api.example.com/openapi.json",
|
|
93
|
+
"API_ACCESS_TOKEN": "your_token_here",
|
|
94
|
+
"MCP_MODE": "stdio",
|
|
95
|
+
"ENABLE_HTTP_ENDPOINT": "false"
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Claude Desktop injects the `env` block values directly into the process — this is the standard MCP pattern.
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## Environment Variable Reference
|
|
107
|
+
|
|
108
|
+
| Variable | Required | Default | Description |
|
|
109
|
+
|----------|----------|---------|-------------|
|
|
110
|
+
| `REST_API_BASE_URL` | Yes | — | REST API base URL |
|
|
111
|
+
| `OPENAPI_SPEC_URL` | Yes | — | OpenAPI/Swagger spec URL or local file path |
|
|
112
|
+
| `AUTH_TYPE` | No | `bearer` | Auth method: `bearer`, `apikey`, `basic`, `none` |
|
|
113
|
+
| `API_ACCESS_TOKEN` | No | — | Bearer token for auth |
|
|
114
|
+
| `API_KEY_HEADER` | No | `X-API-Key` | Header name for API key auth |
|
|
115
|
+
| `API_KEY_VALUE` | No | — | API key value |
|
|
116
|
+
| `BASIC_AUTH_USERNAME` | No | — | Username for basic auth |
|
|
117
|
+
| `BASIC_AUTH_PASSWORD` | No | — | Password for basic auth |
|
|
118
|
+
| `MCP_MODE` | No | `stdio` | `stdio` or `http` |
|
|
119
|
+
| `ENABLE_HTTP_ENDPOINT` | No | `true` | Enable HTTP health/metrics endpoints |
|
|
120
|
+
| `MCP_SERVER_PORT` | No | `8080` | HTTP server port |
|
|
121
|
+
| `MCP_SERVER_HOST` | No | `0.0.0.0` | HTTP server host |
|
|
122
|
+
| `LOG_LEVEL` | No | `INFO` | Logging verbosity |
|
|
123
|
+
| `REQUEST_TIMEOUT` | No | `30` | Request timeout in seconds |
|
|
124
|
+
| `SCHEMA_CACHE_TTL` | No | `3600` | Schema cache TTL in seconds |
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## Operating Modes
|
|
129
|
+
|
|
130
|
+
### MCP Mode (`stdio`) — for Claude Desktop, Cursor, MCP clients
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
restapi-mcp-server --base-url https://api.example.com --spec-url https://api.example.com/openapi.json --mode stdio
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Communicates via stdin/stdout. No HTTP server is started. This is the default.
|
|
137
|
+
|
|
138
|
+
### HTTP Mode — for Docker, Kubernetes, server deployments
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
restapi-mcp-server --base-url https://api.example.com --spec-url https://api.example.com/openapi.json --mode http --port 8080
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Starts an HTTP server with health and metrics endpoints:
|
|
145
|
+
- `GET /` — server info
|
|
146
|
+
- `GET /health` — health check
|
|
147
|
+
- `GET /metrics` — server metrics
|
|
148
|
+
- `GET /schema` — OpenAPI schema summary
|
|
149
|
+
- `GET /tools` — all generated tools
|
|
150
|
+
- `GET /api/endpoints` — all API endpoints
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## Authentication Methods
|
|
155
|
+
|
|
156
|
+
### Bearer Token
|
|
157
|
+
|
|
158
|
+
```env
|
|
159
|
+
AUTH_TYPE=bearer
|
|
160
|
+
API_ACCESS_TOKEN=your_token
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
### API Key
|
|
164
|
+
|
|
165
|
+
```env
|
|
166
|
+
AUTH_TYPE=apikey
|
|
167
|
+
API_KEY_HEADER=X-API-Key
|
|
168
|
+
API_KEY_VALUE=your_key
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
### Basic Authentication
|
|
172
|
+
|
|
173
|
+
```env
|
|
174
|
+
AUTH_TYPE=basic
|
|
175
|
+
BASIC_AUTH_USERNAME=username
|
|
176
|
+
BASIC_AUTH_PASSWORD=password
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
### No Authentication
|
|
180
|
+
|
|
181
|
+
```env
|
|
182
|
+
AUTH_TYPE=none
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
## Docker
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
docker build -t restapi-mcp-server .
|
|
191
|
+
|
|
192
|
+
docker run -p 8080:8080 \
|
|
193
|
+
-e REST_API_BASE_URL=https://api.example.com \
|
|
194
|
+
-e OPENAPI_SPEC_URL=https://api.example.com/openapi.json \
|
|
195
|
+
-e API_ACCESS_TOKEN=your_token \
|
|
196
|
+
-e MCP_MODE=http \
|
|
197
|
+
restapi-mcp-server
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Or with Docker Compose:
|
|
201
|
+
|
|
202
|
+
```bash
|
|
203
|
+
cp .env.example .env # fill in your values
|
|
204
|
+
docker-compose up
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
---
|
|
208
|
+
|
|
209
|
+
## Available Tools
|
|
210
|
+
|
|
211
|
+
The server dynamically generates the following tool types:
|
|
212
|
+
|
|
213
|
+
### Endpoint Tools
|
|
214
|
+
Named by HTTP method and path: `<method>_<path_parts>`
|
|
215
|
+
|
|
216
|
+
Examples:
|
|
217
|
+
- `get_users`
|
|
218
|
+
- `post_users`
|
|
219
|
+
- `get_users_by_id`
|
|
220
|
+
- `delete_users_by_id`
|
|
221
|
+
- `put_users_by_id`
|
|
222
|
+
|
|
223
|
+
### Utility Tools
|
|
224
|
+
- `list_available_endpoints` — list all endpoints (filterable by method or path)
|
|
225
|
+
- `get_endpoint_info` — detailed info about a specific endpoint
|
|
226
|
+
- `get_schema_info` — OpenAPI schema summary or specific model details
|
|
227
|
+
- `execute_custom_request` — run any HTTP request with full control
|
|
228
|
+
- `health_check` — server health and schema status
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
232
|
+
## OpenAPI Specification Support
|
|
233
|
+
|
|
234
|
+
- OpenAPI 3.x (full support)
|
|
235
|
+
- Swagger 2.0 (backward compatible)
|
|
236
|
+
|
|
237
|
+
Supported spec sources:
|
|
238
|
+
- Remote JSON URL
|
|
239
|
+
- Remote YAML URL
|
|
240
|
+
- Local JSON file
|
|
241
|
+
- Local YAML file
|
|
242
|
+
|
|
243
|
+
---
|
|
244
|
+
|
|
245
|
+
## Key Features
|
|
246
|
+
|
|
247
|
+
- **Zero config endpoints** — auto-parses any OpenAPI/Swagger spec and generates MCP tools
|
|
248
|
+
- **Dual mode** — stdio for MCP clients, HTTP for server deployments
|
|
249
|
+
- **Flexible config** — CLI args, env vars, .env file, or Claude Desktop env block
|
|
250
|
+
- **Multiple auth methods** — Bearer, API key, Basic, or none
|
|
251
|
+
- **Production ready** — Docker, Kubernetes, AWS ECS, Google Cloud Run compatible
|
|
252
|
+
- **Self-documenting** — `list_available_endpoints`, `get_endpoint_info`, `get_schema_info` tools built in
|
|
253
|
+
|
|
254
|
+
---
|
|
255
|
+
|
|
256
|
+
## Troubleshooting
|
|
257
|
+
|
|
258
|
+
**`[ERROR] REST API base URL not configured`**
|
|
259
|
+
|
|
260
|
+
Set `REST_API_BASE_URL` via any method above. The most common fix:
|
|
261
|
+
```bash
|
|
262
|
+
restapi-mcp-server --base-url https://your-api.com
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
**`[ERROR] OpenAPI spec URL not configured`**
|
|
266
|
+
|
|
267
|
+
Set `OPENAPI_SPEC_URL` via any method above:
|
|
268
|
+
```bash
|
|
269
|
+
restapi-mcp-server --spec-url https://your-api.com/openapi.json
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
**Port already in use**
|
|
273
|
+
|
|
274
|
+
Change the port:
|
|
275
|
+
```bash
|
|
276
|
+
restapi-mcp-server --mode http --port 9090
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
**Docker container exits immediately**
|
|
280
|
+
|
|
281
|
+
Make sure you're using HTTP mode:
|
|
282
|
+
```bash
|
|
283
|
+
docker run -e MCP_MODE=http -e REST_API_BASE_URL=... -e OPENAPI_SPEC_URL=... restapi-mcp-server
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
**Schema not loading**
|
|
287
|
+
|
|
288
|
+
- Verify the spec URL is reachable
|
|
289
|
+
- Check the format is valid JSON or YAML
|
|
290
|
+
- Ensure the spec is OpenAPI 3.x or Swagger 2.0
|
|
291
|
+
|
|
292
|
+
---
|
|
293
|
+
|
|
294
|
+
## License
|
|
295
|
+
|
|
296
|
+
MIT
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "nife-restapi-mcp-server"
|
|
7
|
+
version = "1.0.0"
|
|
8
|
+
description = "Dynamic MCP server that auto-generates tools from any REST API OpenAPI/Swagger schema"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = { file = "LICENSE" }
|
|
11
|
+
requires-python = ">=3.11"
|
|
12
|
+
authors = [
|
|
13
|
+
{ name = "Varun S", email = "varun@nife.io" }
|
|
14
|
+
]
|
|
15
|
+
keywords = ["mcp", "restapi", "openapi", "swagger", "llm", "claude", "ai", "model-context-protocol"]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Programming Language :: Python :: 3",
|
|
18
|
+
"Programming Language :: Python :: 3.11",
|
|
19
|
+
"Programming Language :: Python :: 3.12",
|
|
20
|
+
"License :: OSI Approved :: MIT License",
|
|
21
|
+
"Operating System :: OS Independent",
|
|
22
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
23
|
+
"Intended Audience :: Developers",
|
|
24
|
+
]
|
|
25
|
+
dependencies = [
|
|
26
|
+
"requests>=2.31.0",
|
|
27
|
+
"python-dotenv>=1.0.0",
|
|
28
|
+
"pyyaml>=6.0.1",
|
|
29
|
+
"aiohttp>=3.9.0",
|
|
30
|
+
"python-json-logger>=2.0.7",
|
|
31
|
+
]
|
|
32
|
+
|
|
33
|
+
[project.optional-dependencies]
|
|
34
|
+
dev = [
|
|
35
|
+
"pytest>=7.4.0",
|
|
36
|
+
"pytest-asyncio>=0.21.0",
|
|
37
|
+
"pytest-cov>=4.1.0",
|
|
38
|
+
"mypy>=1.7.0",
|
|
39
|
+
"types-requests>=2.31.0",
|
|
40
|
+
"types-pyyaml>=6.0.12",
|
|
41
|
+
]
|
|
42
|
+
|
|
43
|
+
[project.scripts]
|
|
44
|
+
restapi-mcp-server = "restapi_mcp_server.__main__:main_sync"
|
|
45
|
+
|
|
46
|
+
[project.urls]
|
|
47
|
+
Repository = "https://github.com/nifetency/nife-mcp-restapi"
|
|
48
|
+
|
|
49
|
+
[tool.setuptools.packages.find]
|
|
50
|
+
where = ["src"]
|