Ahmad-A0/silverbullet-mcp
If you are the rightful owner of silverbullet-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The SilverBullet MCP Server is a bridge that connects Large Language Models (LLMs) and other MCP-compatible clients to your SilverBullet notes and data.
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
-
Clone the repository:
git clone <repository-url> cd <repository-name>
-
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 tohttp://silverbullet:3000
in thedocker-compose.yml
.PORT
: (Optional if running via docker-compose as defined) The port the MCP server will listen on. Defaults to4000
.
-
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 ifDockerfile
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 athttp://localhost:4000
. - Build the Docker image for the
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 ofMCP_TOKEN
you have set in your.env
file for thesilverbullet-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 findmcp-remote
. You might need to add-y
as the first argument toargs
(e.g.,["-y", "mcp-remote", ...]
) or installmcp-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:
-
Authorization Header (Recommended):
- Header Name:
Authorization
- Header Value:
Bearer YOUR_MCP_TOKEN
- Header Name:
-
Query Parameter:
- Append
?token=YOUR_MCP_TOKEN
to the server URL. - Example:
http://localhost:4000/mcp?token=YOUR_MCP_TOKEN
- Append
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.