{"id":31751514,"url":"https://github.com/bitwarden/mcp-server","last_synced_at":"2025-10-09T16:24:12.749Z","repository":{"id":303833463,"uuid":"989261022","full_name":"bitwarden/mcp-server","owner":"bitwarden","description":"MCP server for interaction with the Bitwarden vault.","archived":false,"fork":false,"pushed_at":"2025-10-06T15:47:23.000Z","size":497,"stargazers_count":94,"open_issues_count":4,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-06T16:17:38.430Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitwarden.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-23T19:03:55.000Z","updated_at":"2025-10-06T14:40:34.000Z","dependencies_parsed_at":"2025-07-09T23:26:43.725Z","dependency_job_id":"0bd0643a-7167-4039-bf22-70bbb154c53a","html_url":"https://github.com/bitwarden/mcp-server","commit_stats":null,"previous_names":["bitwarden/mcp-server"],"tags_count":9,"template":false,"template_full_name":"bitwarden/template","purl":"pkg:github/bitwarden/mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitwarden%2Fmcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitwarden%2Fmcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitwarden%2Fmcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitwarden%2Fmcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitwarden","download_url":"https://codeload.github.com/bitwarden/mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitwarden%2Fmcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001766,"owners_count":26083171,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-09T16:24:00.893Z","updated_at":"2025-10-09T16:24:12.742Z","avatar_url":"https://github.com/bitwarden.png","language":"TypeScript","funding_links":[],"categories":["Servers","📚 Projects (2474 total)"],"sub_categories":["Security","MCP Servers"],"readme":"# Bitwarden MCP Server\n\nModel Context Protocol (MCP) server that enables interaction with the Bitwarden password manager vault via the MCP protocol. The server provides two complementary interfaces:\n\n- **CLI-based tools**: Personal vault management and organization operations using the Bitwarden CLI\n- **API-based tools**: Enterprise organization administration using the Bitwarden Public API\n\nThis dual approach allows AI models to securely manage both personal vault items and organization-level resources through defined tool interfaces.\n\n## Prerequisites\n\n- Node.js 22\n- **For CLI operations**: Bitwarden CLI (`bw`) installed, authenticated, and valid session token\n- **For API operations**: Bitwarden organization with API access and valid client credentials\n\n## Installation\n\n### Option One: Configuration in your AI app\n\nOpen up your application configuration, e.g. for Claude Desktop:\n\n```json\n{\n  \"mcpServers\": {\n    \"bitwarden\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@bitwarden/mcp-server\"]\n    }\n  }\n}\n```\n\n### Option Two: Local checkout\n\nRequires that this repository be checked out locally. Once that's done:\n\n```bash\nnpm install\nnpm run build\n```\n\n## Setup\n\nThe server supports two authentication methods:\n\n### Option A: CLI Authentication (for personal vault operations)\n\n1. **Install Bitwarden CLI**:\n\n   ```bash\n   npm install -g @bitwarden/cli\n   ```\n\n2. **Log in to Bitwarden**:\n\n   ```bash\n   bw login\n   ```\n\n3. **Get session token**:\n   ```bash\n   export BW_SESSION=$(bw unlock --raw)\n   ```\n\n### Option B: API Authentication (for organization management)\n\n1. **Create API credentials** in your Bitwarden organization settings\n\n2. **Set environment variables**:\n\n   ```bash\n   export BW_CLIENT_ID=\"your_client_id\"\n   export BW_CLIENT_SECRET=\"your_client_secret\"\n   ```\n\n3. **Optional: Set custom API URLs** (if using self-hosted):\n   ```bash\n   export BW_API_BASE_URL=\"https://api.bitwarden.com\"\n   export BW_IDENTITY_URL=\"https://identity.bitwarden.com\"\n   ```\n\n\u003e **Note**: You can use both authentication methods simultaneously for full functionality.\n\n## Testing\n\n### Running unit tests\n\nThe project includes Jest unit tests covering validation, CLI commands, and core functionality.\n\n```bash\n# Run all tests\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n\n# Run tests with coverage\nnpm test -- --coverage\n\n# Run specific test file\nnpm test validation.spec.ts\n\n# Run tests matching a pattern\nnpm test -- --testNamePattern=\"validation\"\n```\n\n## Inspection and development\n\n### MCP Inspector\n\nUse the MCP Inspector to test the server interactively:\n\n```bash\n# Start the inspector\nnpm run inspect\n```\n\nThis will:\n\n1. Start the MCP server\n2. Launch the inspector UI in your browser\n3. Allow you to test all available tools interactively\n\n### Available tools\n\nThe server provides comprehensive Bitwarden functionality through two authentication methods:\n\n**CLI Authentication** is used for:\n\n- Personal vault operations (items, folders, passwords)\n- Quick organization queries (list members, collections)\n- Organization member confirmation workflows\n- Collection creation and editing\n- Item collection assignments\n\n**API Authentication** is used for:\n\n- Full organization administration (members, groups, policies)\n- Bulk operations and automation\n- Advanced permission management\n- Audit log retrieval\n- Subscription management\n\n\u003e **Note**: You can use both authentication methods simultaneously. The CLI tools are lighter-weight for simple operations, while API tools provide comprehensive organization management.\n\n#### Personal Vault Tools (CLI Authentication)\n\n##### Session Management\n\n| Tool     | Description      | Required Parameters |\n| -------- | ---------------- | ------------------- |\n| `lock`   | Lock the vault   | None                |\n| `sync`   | Sync vault data  | None                |\n| `status` | Check CLI status | None                |\n\n##### Vault Items and Folders\n\n| Tool                    | Description                                                   | Required Parameters                                                                                                                                                                                                                                                                                                                              |\n| ----------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `list`                  | List vault items/folders with optional filters                | `type` (items/folders/collections/organizations/org-members/org-collections), optional `url`, `folderid`, `collectionid`, `trash`                                                                                                                                                                                                                |\n| `get`                   | Get specific item/folder/fingerprint/attachment               | `object` (item/username/password/uri/totp/notes/exposed/attachment/folder/collection/organization/org-collection/fingerprint), `id` (use \"me\" for fingerprint or filename for attachment), optional `organizationid` for org-collection, optional `itemid` (required for attachment), optional `output` (directory path for attachment download) |\n| `generate`              | Generate password/passphrase                                  | Various optional parameters                                                                                                                                                                                                                                                                                                                      |\n| `create_item`           | Create new vault item (login, secure note, card, identity)    | `name`, `type`, type-specific data, optional `notes`, `folderId`                                                                                                                                                                                                                                                                                 |\n| `create_folder`         | Create new folder                                             | `name`                                                                                                                                                                                                                                                                                                                                           |\n| `edit_item`             | Edit existing vault item                                      | `id`, optional `name`, `notes`, type-specific data, `folderId`                                                                                                                                                                                                                                                                                   |\n| `edit_folder`           | Edit existing folder                                          | `id`, `name`                                                                                                                                                                                                                                                                                                                                     |\n| `edit_item_collections` | Edit which collections an item belongs to                     | `itemId`, `organizationId`, `collectionIds` (array)                                                                                                                                                                                                                                                                                              |\n| `move`                  | Move (share) a vault item to an organization with collections | `itemId`, `organizationId`, `collectionIds` (array)                                                                                                                                                                                                                                                                                              |\n| `delete`                | Delete vault item/folder/attachment                           | `object` (item/folder/attachment), `id`, optional `permanent`                                                                                                                                                                                                                                                                                    |\n| `restore`               | Restore item from trash                                       | `object`, `id`                                                                                                                                                                                                                                                                                                                                   |\n| `create_attachment`     | Attach a file to a vault item                                 | `filePath`, `itemId`                                                                                                                                                                                                                                                                                                                             |\n\n##### Bitwarden Send Tools\n\n| Tool                   | Description                            | Required Parameters                                                             |\n| ---------------------- | -------------------------------------- | ------------------------------------------------------------------------------- |\n| `create_text_send`     | Create a text Send for secure sharing  | `name`, `text`, optional `hidden`, `notes`, `password`, `maxAccessCount`, dates |\n| `create_file_send`     | Create a file Send for secure sharing  | `name`, `filePath`, optional `notes`, `password`, `maxAccessCount`, dates       |\n| `list_send`            | List all Sends                         | None                                                                            |\n| `get_send`             | Get Send details                       | `id`                                                                            |\n| `edit_send`            | Edit existing Send                     | `id`, optional `name`, `notes`, `password`, `maxAccessCount`, dates, `disabled` |\n| `delete_send`          | Delete a Send                          | `id`                                                                            |\n| `remove_send_password` | Remove password protection from a Send | `id`                                                                            |\n\n##### Organization Operations (CLI)\n\n| Tool                          | Description                                       | Required Parameters                                         |\n| ----------------------------- | ------------------------------------------------- | ----------------------------------------------------------- |\n| `confirm`                     | Confirm invited organization member               | `organizationId`, `memberId`                                |\n| `create_org_collection`       | Create new organization collection                | `organizationId`, `name`, optional `externalId`, `groups`   |\n| `edit_org_collection`         | Edit existing organization collection             | `organizationId`, `collectionId`, optional `name`, `groups` |\n| `device_approval_list`        | List pending device approval requests             | `organizationId`                                            |\n| `device_approval_approve`     | Approve a device authorization request            | `organizationId`, `requestId`                               |\n| `device_approval_approve_all` | Approve all pending device authorization requests | `organizationId`                                            |\n| `device_approval_deny`        | Deny a device authorization request               | `organizationId`, `requestId`                               |\n| `device_approval_deny_all`    | Deny all pending device authorization requests    | `organizationId`                                            |\n\n\u003e **Note**: Device approval commands are only available to organization admins/owners for managing trusted device approval requests.\n\n#### Organization Management Tools (API Authentication)\n\n##### Collections Management\n\n| Tool                    | Description                   | Required Parameters |\n| ----------------------- | ----------------------------- | ------------------- |\n| `list_org_collections`  | List organization collections | None                |\n| `get_org_collection`    | Get collection details        | `id`                |\n| `update_org_collection` | Update existing collection    | `id`                |\n| `delete_org_collection` | Delete collection             | `id`                |\n\n##### Members Management\n\n| Tool                       | Description                       | Required Parameters |\n| -------------------------- | --------------------------------- | ------------------- |\n| `list_org_members`         | List organization members         | None                |\n| `get_org_member`           | Get member details                | `id`                |\n| `invite_org_member`        | Invite new member                 | `email`, `type`     |\n| `update_org_member`        | Update existing member            | `id`                |\n| `remove_org_member`        | Remove member from organization   | `id`                |\n| `reinvite_org_member`      | Re-invite member                  | `id`                |\n| `get_org_member_groups`    | Get member's group assignments    | `id`                |\n| `update_org_member_groups` | Update member's group assignments | `id`, `groupIds`    |\n\n##### Groups Management\n\n| Tool                       | Description                       | Required Parameters |\n| -------------------------- | --------------------------------- | ------------------- |\n| `list_org_groups`          | List organization groups          | None                |\n| `get_org_group`            | Get group details                 | `id`                |\n| `create_org_group`         | Create new group                  | `name`              |\n| `update_org_group`         | Update existing group             | `id`, `name`        |\n| `delete_org_group`         | Delete group                      | `id`                |\n| `get_org_group_members`    | Get group's member assignments    | `id`                |\n| `update_org_group_members` | Update group's member assignments | `id`, `memberIds`   |\n\n##### Policies Management\n\n| Tool                | Description                | Required Parameters |\n| ------------------- | -------------------------- | ------------------- |\n| `list_org_policies` | List organization policies | None                |\n| `get_org_policy`    | Get policy details         | `type`              |\n| `update_org_policy` | Update organization policy | `type`, `enabled`   |\n\n##### Organization Management\n\n| Tool                          | Description                  | Required Parameters |\n| ----------------------------- | ---------------------------- | ------------------- |\n| `get_org_subscription`        | Get subscription details     | None                |\n| `update_org_subscription`     | Update subscription settings | None                |\n| `import_org_users_and_groups` | Import members and groups    | None                |\n\n##### Events and Auditing\n\n| Tool             | Description                 | Required Parameters |\n| ---------------- | --------------------------- | ------------------- |\n| `get_org_events` | Get organization audit logs | None                |\n\n### Manual testing\n\n1. **Start the server**:\n\n   ```bash\n   export BW_SESSION=$(bw unlock --raw)\n   node dist/index.js\n   ```\n\n2. **Test with an MCP client** or use the inspector to send tool requests.\n\n### Debugging\n\n- **Enable debug logging** by setting environment variables:\n\n  ```bash\n  export DEBUG=bitwarden:*\n  export NODE_ENV=development\n  ```\n\n- **Check Bitwarden CLI status**:\n\n  ```bash\n  bw status\n  ```\n\n- **Verify session token**:\n  ```bash\n  echo $BW_SESSION\n  ```\n\n## Security considerations\n\n- **Never commit** sensitive credentials (`BW_SESSION`, `BW_CLIENT_ID`, `BW_CLIENT_SECRET`)\n- **Use environment variables** for all sensitive configuration\n- **Validate all inputs** using Zod schemas (already implemented)\n- **Test with non-production data** when possible\n- **Monitor API usage** through your organization's audit logs\n- **Use HTTPS** for all API communications (default)\n- 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.\n\n## Troubleshooting\n\n### Common issues\n\n1. **\"Please set the BW_SESSION environment variable\"**\n   - Run: `export BW_SESSION=$(bw unlock --raw)`\n\n2. **\"BW_CLIENT_ID and BW_CLIENT_SECRET environment variables are required\"**\n   - Set your API credentials: `export BW_CLIENT_ID=\"your_id\"` and `export BW_CLIENT_SECRET=\"your_secret\"`\n   - Verify credentials are valid in your Bitwarden organization settings\n\n3. **API authentication failures**\n   - Check that your organization has API access enabled\n   - Verify client credentials have appropriate permissions\n   - Ensure you're using the correct API URLs for your instance\n\n4. **Tests failing with environment errors**\n   - Use the environment mocking helpers in tests\n   - Ensure test cleanup with `restoreEnvVars()`\n\n5. **Inspector not starting**\n   - Check that the server builds successfully: `npm run build`\n   - Verify Node.js version is 22\n\n6. **CLI commands failing**\n   - Verify Bitwarden CLI is installed: `bw --version`\n   - Check vault is unlocked: `bw status`\n   - Ensure valid session token: `echo $BW_SESSION`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitwarden%2Fmcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitwarden%2Fmcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitwarden%2Fmcp-server/lists"}