Ahmad-A0/silverbullet-mcp

SilverBullet MCP Server

This project provides a Model Context Protocol (MCP) server that acts as a bridge to your SilverBullet instance. It enables Large Language Models (LLMs) and other MCP-compatible clients to interact with your SilverBullet notes and data by exposing them through standardized MCP tools and resources.

The server is designed to be run via Docker Compose alongside your existing SilverBullet Docker container. It handles authentication and provides a secure way for external applications to access and manipulate your SilverBullet space.

Asking Claude to create a retirement projection, based on my notes.

Prerequisites

• Docker
• Docker Compose

Getting Started

1. Clone the repository:

   git clone <repository-url>
   cd <repository-name>
   

2. Create an environment file: Copy the contents of .env.example to a new file named .env.

   cp .env.example .env
   

   Update the .env file with your specific values:

   • SB_AUTH_TOKEN: A secure token for SilverBullet to authenticate with this MCP server and for this MCP server to authenticate with SilverBullet.
   • MCP_TOKEN: A secure token for clients (e.g., your AI model) to authenticate with this MCP server.
   • SB_API_BASE_URL: (Optional if running via docker-compose as defined) The base URL for the SilverBullet API. Defaults to http://silverbullet:3000 in the docker-compose.yml.
   • PORT: (Optional if running via docker-compose as defined) The port the MCP server will listen on. Defaults to 4000.

3. Build and run the services using Docker Compose:

   docker-compose up --build
   

   This command will:

   • Build the Docker image for the silverbullet-mcp-server if it doesn't exist or if Dockerfile or related files have changed.
   • Pull the latest silverbulletmd/silverbullet image.
   • Start both the SilverBullet instance and the MCP server.

   The SilverBullet instance will be accessible at http://localhost:3000. The MCP server will be accessible at http://localhost:4000.

Connecting to the MCP Server

This MCP server runs as part of a Docker Compose setup and will be accessible at http://localhost:4000 by default.

You can connect to this server using an MCP client. The method of connection and authentication depends on the client's capabilities.

Using mcp-remote (for stdio-only clients)

If your MCP client only supports stdio connections (e.g., older versions of Claude Desktop, Cursor, Windsurf), you can use mcp-remote to bridge the connection to this HTTP-based MCP server.

mcp-remote acts as a local stdio MCP server that proxies requests to a remote HTTP MCP server, handling authentication in the process.

Client Configuration with Authentication:

This MCP server requires token-based authentication. Configure your MCP client (e.g., in claude_desktop_config.json, ~/.cursor/mcp.json, or ~/.codeium/windsurf/mcp_config.json) to use mcp-remote and pass the MCP_TOKEN via a custom header:

{
  "mcpServers": {
    "silverbullet-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:4000/mcp", 
        "--transport",
        "http-only",
        "--header",
        "Authorization:Bearer ${MCP_SERVER_TOKEN}" 
      ],
      "env": {
        "MCP_SERVER_TOKEN": "your_actual_mcp_token_from_dotenv"
      }
    }
  }
}

Important:

• Replace "your_actual_mcp_token_from_dotenv" with the actual value of MCP_TOKEN you have set in your .env file for the silverbullet-mcp-server.
• Some clients (like Cursor and Claude Desktop on Windows) have issues with spaces in args. The example above (Authorization:Bearer ${MCP_SERVER_TOKEN}) avoids this.
• Ensure npx can find mcp-remote. You might need to add -y as the first argument to args (e.g., ["-y", "mcp-remote", ...]) or install mcp-remote globally (npm install -g mcp-remote).

Refer to the mcp-remote documentation for more advanced configurations, including OAuth support (not used by this server's default auth), different transport strategies, and troubleshooting.

Direct Connection (for Streamable HTTP clients)

If your MCP client supports Streamable HTTP transport and can send custom headers, you can connect to it directly.

The server supports two methods for token-based authentication:

1. Authorization Header (Recommended):

   • Header Name: Authorization
   • Header Value: Bearer YOUR_MCP_TOKEN

2. Query Parameter:

   • Append ?token=YOUR_MCP_TOKEN to the server URL.
   • Example: http://localhost:4000/mcp?token=YOUR_MCP_TOKEN

Replace YOUR_MCP_TOKEN with the actual value of the MCP_TOKEN environment variable set in your .env file.

Endpoint: http://localhost:4000/mcp (or as configured by PORT if not using Docker Compose defaults).

Consult your MCP client's documentation on how to configure connections to remote HTTP MCP servers, including how to send custom headers or append query parameters.