silverbullet

SilverBullet MCP Server acts as an MCP bridge that exposes your SilverBullet space as MCP tools and resources, enabling LLMs and other MCP-compatible clients to interact with notes and data through standardized MCP endpoints. It is designed to run alongside a SilverBullet container inside a Docker Compose setup. Clients authenticate using tokens (MCP_TOKEN for clients and SB_AUTH_TOKEN for SilverBullet authentication with the MCP server). You can connect via direct HTTP to the MCP server or use mcp-remote for stdio-based clients to bridge to the HTTP API. The server exposes an /mcp endpoint that client tools will interact with, and it handles authentication and access to SilverBullet data through MCP tools and resources.

Prerequisites:

• Docker and Docker Compose installed on your machine
• Access to the SilverBullet Docker image and a compatible SilverBullet setup

Install and run:

1. Clone the repository and navigate into it: git clone <repository-url> cd <repository-name>

2. Create and configure environment variables:

   • Copy the example env file: cp .env.example .env
   • Edit .env to include: SB_AUTH_TOKEN: your_silverbullet_auth_token MCP_TOKEN: your_mcp_token_for_clients SB_API_BASE_URL: http://silverbullet:3000 (or your SB base URL) PORT: 4000 (or your desired MCP server port)

3. Start the services with Docker Compose (recommended): docker-compose up --build

4. If you’re running the MCP server standalone (without docker-compose):

   • Build/pull the SilverBullet MCP image and run it using the provided docker command with the appropriate environment variables: docker run -d -p 4000:4000
     -e SB_AUTH_TOKEN=your_silverbullet_auth_token
     -e MCP_TOKEN=your_mcp_token_for_clients
     -e SB_API_BASE_URL=http://silverbullet:3000
     -e PORT=4000
     silverbullet-mcp-server

5. Verify: The SilverBullet instance should be accessible at http://localhost:3000 and the MCP server at http://localhost:4000 by default (adjust ports if you changed PORT).

Tips and common issues:

• Ensure SB_AUTH_TOKEN and MCP_TOKEN are kept secure and not committed to source control.
• If you use docker-compose, the SB_API_BASE_URL is typically set to http://silverbullet:3000 within the compose network; adjust only if you customize networking.
• The MCP server uses token-based authentication; when configuring MCP clients (e.g., mcp-remote), pass MCP_TOKEN via headers or configuration as described in the README.
• If you encounter connection issues, verify that the MCP server container can reach the SilverBullet container at the SB_API_BASE_URL and that the ports are correctly exposed.
• For stdio-based clients, consider using mcp-remote to bridge to HTTP, and remember to include -y in the arguments if needed for compatibility with your client.
• If you modify the port, update both the .env PORT value and your client connection URLs accordingly.