@bitwarden/mcp-server 2025.7.0-beta.1
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/LICENSE.txt +674 -0
- package/README.md +153 -0
- package/dist/index.js +973 -0
- package/package.json +59 -0
package/README.md
ADDED
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
# Bitwarden MCP Server
|
|
2
|
+
|
|
3
|
+
Model Context Protocol (MCP) server that enables interaction with the Bitwarden password manager vault via the MCP protocol. The server allows AI models to securely communicate with a user's Bitwarden vault through defined tool interfaces.
|
|
4
|
+
|
|
5
|
+
## Prerequisites
|
|
6
|
+
|
|
7
|
+
- Node.js 18+
|
|
8
|
+
- Bitwarden CLI (`bw`) installed and authenticated
|
|
9
|
+
- Valid Bitwarden session token
|
|
10
|
+
|
|
11
|
+
## Installation
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm install
|
|
15
|
+
npm run build
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Setup
|
|
19
|
+
|
|
20
|
+
1. **Install Bitwarden CLI**:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npm install -g @bitwarden/cli
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
2. **Log in to Bitwarden**:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
bw login
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
3. **Get session token**:
|
|
33
|
+
```bash
|
|
34
|
+
export BW_SESSION=$(bw unlock --raw)
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Testing
|
|
38
|
+
|
|
39
|
+
### Running unit tests
|
|
40
|
+
|
|
41
|
+
The project includes Jest unit tests covering validation, CLI commands, and core functionality.
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
# Run all tests
|
|
45
|
+
npm test
|
|
46
|
+
|
|
47
|
+
# Run tests in watch mode
|
|
48
|
+
npm run test:watch
|
|
49
|
+
|
|
50
|
+
# Run tests with coverage
|
|
51
|
+
npm test -- --coverage
|
|
52
|
+
|
|
53
|
+
# Run specific test file
|
|
54
|
+
npm test validation.spec.ts
|
|
55
|
+
|
|
56
|
+
# Run tests matching a pattern
|
|
57
|
+
npm test -- --testNamePattern="validation"
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Inspection and development
|
|
61
|
+
|
|
62
|
+
### MCP Inspector
|
|
63
|
+
|
|
64
|
+
Use the MCP Inspector to test the server interactively:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
# Start the inspector
|
|
68
|
+
npm run inspect
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
This will:
|
|
72
|
+
|
|
73
|
+
1. Start the MCP server
|
|
74
|
+
2. Launch the inspector UI in your browser
|
|
75
|
+
3. Allow you to test all available tools interactively
|
|
76
|
+
|
|
77
|
+
### Available tools
|
|
78
|
+
|
|
79
|
+
The server provides the following Bitwarden CLI tools:
|
|
80
|
+
|
|
81
|
+
| Tool | Description | Required Parameters |
|
|
82
|
+
| ---------- | ---------------------------- | ------------------------------------------------- |
|
|
83
|
+
| `lock` | Lock the vault | None |
|
|
84
|
+
| `unlock` | Unlock with master password | `password` |
|
|
85
|
+
| `sync` | Sync vault data | None |
|
|
86
|
+
| `status` | Check CLI status | None |
|
|
87
|
+
| `list` | List vault items/folders | `type` (items/folders/collections/organizations) |
|
|
88
|
+
| `get` | Get specific item/folder | `object`, `id` |
|
|
89
|
+
| `generate` | Generate password/passphrase | Various optional parameters |
|
|
90
|
+
| `create` | Create new item or folder | `objectType`, `name`, additional fields for items |
|
|
91
|
+
| `edit` | Edit existing item or folder | `objectType`, `id`, optional fields to update |
|
|
92
|
+
| `delete` | Delete vault item/folder | `object`, `id`, optional `permanent` |
|
|
93
|
+
|
|
94
|
+
### Manual testing
|
|
95
|
+
|
|
96
|
+
1. **Start the server**:
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
export BW_SESSION=$(bw unlock --raw)
|
|
100
|
+
node dist/index.js
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
2. **Test with an MCP client** or use the inspector to send tool requests.
|
|
104
|
+
|
|
105
|
+
### Debugging
|
|
106
|
+
|
|
107
|
+
- **Enable debug logging** by setting environment variables:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
export DEBUG=bitwarden:*
|
|
111
|
+
export NODE_ENV=development
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
- **Check Bitwarden CLI status**:
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
bw status
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
- **Verify session token**:
|
|
121
|
+
```bash
|
|
122
|
+
echo $BW_SESSION
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
## Security considerations
|
|
126
|
+
|
|
127
|
+
- **Never commit** the `BW_SESSION` token
|
|
128
|
+
- **Use environment variables** for sensitive configuration
|
|
129
|
+
- **Validate all inputs** using Zod schemas (already implemented)
|
|
130
|
+
- **Test with non-production data** when possible
|
|
131
|
+
|
|
132
|
+
## Troubleshooting
|
|
133
|
+
|
|
134
|
+
### Common issues
|
|
135
|
+
|
|
136
|
+
1. **"Please set the BW_SESSION environment variable"**
|
|
137
|
+
|
|
138
|
+
- Run: `export BW_SESSION=$(bw unlock --raw)`
|
|
139
|
+
|
|
140
|
+
2. **Tests failing with environment errors**
|
|
141
|
+
|
|
142
|
+
- Use the environment mocking helpers in tests
|
|
143
|
+
- Ensure test cleanup with `restoreEnvVars()`
|
|
144
|
+
|
|
145
|
+
3. **Inspector not starting**
|
|
146
|
+
|
|
147
|
+
- Check that the server builds successfully: `npm run build`
|
|
148
|
+
- Verify Node.js version is 18+
|
|
149
|
+
|
|
150
|
+
4. **CLI commands failing**
|
|
151
|
+
- Verify Bitwarden CLI is installed: `bw --version`
|
|
152
|
+
- Check vault is unlocked: `bw status`
|
|
153
|
+
- Ensure valid session token: `echo $BW_SESSION`
|