@bitwarden/mcp-server 2025.8.2 → 2025.9.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.
Files changed (6) hide show
  1. package/README.md +103 -8
  2. package/dist/index.d.ts +41 -0
  3. package/dist/index.d.ts.map +1 -1
  4. package/dist/index.js +2211 -466
  5. package/dist/index.js.map +1 -1
  6. package/package.json +2 -2
package/README.md CHANGED
@@ -5,8 +5,8 @@ Model Context Protocol (MCP) server that enables interaction with the Bitwarden
5
5
  ## Prerequisites
6
6
 
7
7
  - Node.js 22
8
- - Bitwarden CLI (`bw`) installed and authenticated
9
- - Valid Bitwarden session token
8
+ - **For CLI operations**: Bitwarden CLI (`bw`) installed, authenticated, and valid session token
9
+ - **For API operations**: Bitwarden organization with API access and valid client credentials
10
10
 
11
11
  ## Installation
12
12
 
@@ -36,6 +36,10 @@ npm run build
36
36
 
37
37
  ## Setup
38
38
 
39
+ The server supports two authentication methods:
40
+
41
+ ### Option A: CLI Authentication (for personal vault operations)
42
+
39
43
  1. **Install Bitwarden CLI**:
40
44
 
41
45
  ```bash
@@ -53,6 +57,25 @@ npm run build
53
57
  export BW_SESSION=$(bw unlock --raw)
54
58
  ```
55
59
 
60
+ ### Option B: API Authentication (for organization management)
61
+
62
+ 1. **Create API credentials** in your Bitwarden organization settings
63
+
64
+ 2. **Set environment variables**:
65
+
66
+ ```bash
67
+ export BW_CLIENT_ID="your_client_id"
68
+ export BW_CLIENT_SECRET="your_client_secret"
69
+ ```
70
+
71
+ 3. **Optional: Set custom API URLs** (if using self-hosted):
72
+ ```bash
73
+ export BW_API_BASE_URL="https://api.bitwarden.com"
74
+ export BW_IDENTITY_URL="https://identity.bitwarden.com"
75
+ ```
76
+
77
+ > **Note**: You can use both authentication methods simultaneously for full functionality.
78
+
56
79
  ## Testing
57
80
 
58
81
  ### Running unit tests
@@ -95,7 +118,9 @@ This will:
95
118
 
96
119
  ### Available tools
97
120
 
98
- The server provides the following Bitwarden CLI tools:
121
+ The server provides comprehensive Bitwarden functionality through two categories of tools:
122
+
123
+ #### Personal Vault Tools (CLI Authentication)
99
124
 
100
125
  | Tool | Description | Required Parameters |
101
126
  | ---------- | ---------------------------- | ------------------------------------------------- |
@@ -110,6 +135,65 @@ The server provides the following Bitwarden CLI tools:
110
135
  | `edit` | Edit existing item or folder | `objectType`, `id`, optional fields to update |
111
136
  | `delete` | Delete vault item/folder | `object`, `id`, optional `permanent` |
112
137
 
138
+ #### Organization Management Tools (API Authentication)
139
+
140
+ ##### Collections Management
141
+
142
+ | Tool | Description | Required Parameters |
143
+ | ------------------- | ----------------------------- | ------------------- |
144
+ | `list-collections` | List organization collections | None |
145
+ | `get-collection` | Get collection details | `id` |
146
+ | `create-collection` | Create new collection | `name` |
147
+ | `update-collection` | Update existing collection | `id` |
148
+ | `delete-collection` | Delete collection | `id` |
149
+
150
+ ##### Members Management
151
+
152
+ | Tool | Description | Required Parameters |
153
+ | ------------------------- | --------------------------------- | ------------------- |
154
+ | `list-members` | List organization members | None |
155
+ | `get-member` | Get member details | `id` |
156
+ | `invite-member` | Invite new member | `email`, `type` |
157
+ | `update-member` | Update existing member | `id` |
158
+ | `remove-member` | Remove member from organization | `id` |
159
+ | `reinvite-member` | Re-invite member | `id` |
160
+ | `get-member-group-ids` | Get member's group assignments | `id` |
161
+ | `update-member-group-ids` | Update member's group assignments | `id`, `groupIds` |
162
+
163
+ ##### Groups Management
164
+
165
+ | Tool | Description | Required Parameters |
166
+ | ------------------------- | --------------------------------- | ------------------- |
167
+ | `list-groups` | List organization groups | None |
168
+ | `get-group` | Get group details | `id` |
169
+ | `create-group` | Create new group | `name` |
170
+ | `update-group` | Update existing group | `id`, `name` |
171
+ | `delete-group` | Delete group | `id` |
172
+ | `get-group-member-ids` | Get group's member assignments | `id` |
173
+ | `update-group-member-ids` | Update group's member assignments | `id`, `memberIds` |
174
+
175
+ ##### Policies Management
176
+
177
+ | Tool | Description | Required Parameters |
178
+ | --------------- | -------------------------- | ------------------- |
179
+ | `list-policies` | List organization policies | None |
180
+ | `get-policy` | Get policy details | `type` |
181
+ | `update-policy` | Update organization policy | `type`, `enabled` |
182
+
183
+ ##### Organization Management
184
+
185
+ | Tool | Description | Required Parameters |
186
+ | ---------------------------------- | ---------------------------- | ------------------- |
187
+ | `get-organization-subscription` | Get subscription details | None |
188
+ | `update-organization-subscription` | Update subscription settings | None |
189
+ | `import-organization` | Import members and groups | None |
190
+
191
+ ##### Events and Auditing
192
+
193
+ | Tool | Description | Required Parameters |
194
+ | ------------- | --------------------------- | ------------------- |
195
+ | `list-events` | Get organization audit logs | None |
196
+
113
197
  ### Manual testing
114
198
 
115
199
  1. **Start the server**:
@@ -143,10 +227,12 @@ The server provides the following Bitwarden CLI tools:
143
227
 
144
228
  ## Security considerations
145
229
 
146
- - **Never commit** the `BW_SESSION` token
147
- - **Use environment variables** for sensitive configuration
230
+ - **Never commit** sensitive credentials (`BW_SESSION`, `BW_CLIENT_ID`, `BW_CLIENT_SECRET`)
231
+ - **Use environment variables** for all sensitive configuration
148
232
  - **Validate all inputs** using Zod schemas (already implemented)
149
233
  - **Test with non-production data** when possible
234
+ - **Monitor API usage** through your organization's audit logs
235
+ - **Use HTTPS** for all API communications (default)
150
236
  - Understand the security and privacy impacts of exposing sensitive vault data to LLM and AI tools. Using a self-hosted or local LLM may be appropriate, for example.
151
237
 
152
238
  ## Troubleshooting
@@ -156,15 +242,24 @@ The server provides the following Bitwarden CLI tools:
156
242
  1. **"Please set the BW_SESSION environment variable"**
157
243
  - Run: `export BW_SESSION=$(bw unlock --raw)`
158
244
 
159
- 2. **Tests failing with environment errors**
245
+ 2. **"BW_CLIENT_ID and BW_CLIENT_SECRET environment variables are required"**
246
+ - Set your API credentials: `export BW_CLIENT_ID="your_id"` and `export BW_CLIENT_SECRET="your_secret"`
247
+ - Verify credentials are valid in your Bitwarden organization settings
248
+
249
+ 3. **API authentication failures**
250
+ - Check that your organization has API access enabled
251
+ - Verify client credentials have appropriate permissions
252
+ - Ensure you're using the correct API URLs for your instance
253
+
254
+ 4. **Tests failing with environment errors**
160
255
  - Use the environment mocking helpers in tests
161
256
  - Ensure test cleanup with `restoreEnvVars()`
162
257
 
163
- 3. **Inspector not starting**
258
+ 5. **Inspector not starting**
164
259
  - Check that the server builds successfully: `npm run build`
165
260
  - Verify Node.js version is 22
166
261
 
167
- 4. **CLI commands failing**
262
+ 6. **CLI commands failing**
168
263
  - Verify Bitwarden CLI is installed: `bw --version`
169
264
  - Check vault is unlocked: `bw status`
170
265
  - Ensure valid session token: `echo $BW_SESSION`
package/dist/index.d.ts CHANGED
@@ -65,4 +65,45 @@ export declare function buildSafeCommand(baseCommand: string, parameters?: reado
65
65
  * @returns {boolean} True if the command is safe, false otherwise
66
66
  */
67
67
  export declare function isValidBitwardenCommand(command: string): boolean;
68
+ /**
69
+ * Validates that an API endpoint path is safe and matches allowed patterns.
70
+ *
71
+ * @param {string} endpoint - The API endpoint path to validate
72
+ * @returns {boolean} True if the endpoint is safe, false otherwise
73
+ */
74
+ export declare function validateApiEndpoint(endpoint: string): boolean;
75
+ /**
76
+ * Sanitizes API parameters to prevent injection attacks.
77
+ *
78
+ * @param {unknown} params - The parameters to sanitize
79
+ * @returns {unknown} The sanitized parameters
80
+ */
81
+ export declare function sanitizeApiParameters(params: unknown): unknown;
82
+ /**
83
+ * Builds a safe API request with proper authentication and validation.
84
+ *
85
+ * @param {string} endpoint - The API endpoint path
86
+ * @param {string} method - The HTTP method
87
+ * @param {unknown} data - The request data
88
+ * @returns {Promise<RequestInit>} The safe request configuration
89
+ */
90
+ export declare function buildSafeApiRequest(endpoint: string, method: string, data?: unknown): Promise<RequestInit>;
91
+ /**
92
+ * Interface representing the response from a Bitwarden API request.
93
+ */
94
+ export interface ApiResponse {
95
+ data?: unknown;
96
+ errorMessage?: string;
97
+ status: number;
98
+ }
99
+ /**
100
+ * Executes a safe API request to the Bitwarden Public API.
101
+ *
102
+ * @async
103
+ * @param {string} endpoint - The API endpoint path
104
+ * @param {string} method - The HTTP method
105
+ * @param {unknown} data - The request data
106
+ * @returns {Promise<ApiResponse>} A promise that resolves to the API response
107
+ */
108
+ export declare function executeApiRequest(endpoint: string, method: string, data?: unknown): Promise<ApiResponse>;
68
109
  //# sourceMappingURL=index.d.ts.map
package/dist/index.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAYA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA8exB;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA8CD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,EAAE,OAAO,GAEX,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,GAClB,SAAS;IACP,KAAK;IACL;QACE,QAAQ,CAAC,OAAO,EAAE,SAAS;YACzB;gBAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;aAAE;SACjD,CAAC;QACF,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;KACxB;CACF,CA0BJ;AAID;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAuBnD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ1D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,UAAU,GAAE,SAAS,MAAM,EAAO,GACjC,MAAM,CAKR;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CA+BhE"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAYA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgoDxB;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA8CD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,EAAE,OAAO,GAEX,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,GAClB,SAAS;IACP,KAAK;IACL;QACE,QAAQ,CAAC,OAAO,EAAE,SAAS;YACzB;gBAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;aAAE;SACjD,CAAC;QACF,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;KACxB;CACF,CA0BJ;AAID;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAuBnD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ1D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,UAAU,GAAE,SAAS,MAAM,EAAO,GACjC,MAAM,CAKR;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CA+BhE;AAwCD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAwB7D;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAyB9D;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,OAAO,GACb,OAAO,CAAC,WAAW,CAAC,CA+BtB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,OAAO,GACb,OAAO,CAAC,WAAW,CAAC,CAuCtB"}