notehub_mcp_server
If you are the rightful owner of notehub_mcp_server 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 Blues Notehub MCP Server is a Python-based implementation that allows large language models to interact with Blues Notehub projects, devices, and data using the Model Context Protocol (MCP).
Blues Notehub MCP Server (Python)
This is a Model Context Protocol (MCP) server implementation that interacts with the Blues Notehub API using the official notehub_py
SDK. It allows large language models to interface with your Blues Notehub projects, devices, and data.
What is MCP?
Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. It standardizes how LLMs interact with external tools and services.
Prerequisites
- Python 3.8 or higher
- A Blues Notehub account (https://notehub.io)
- Your Notehub account username (email) and password
Installation
Option 1: Using pip (recommended)
- Clone or download this repository.
- Create a virtual environment:
python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
- Install the dependencies:
pip install -r requirements.txt
Option 2: Using uv (faster alternative)
- Install uv following the instructions at https://github.com/astral-sh/uv
- Create the environment and install dependencies:
uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate uv pip install -r requirements.txt
Running the Server
Start the server with:
python notehub.py
The MCP server will run using stdio as the transport layer, which is the standard transport for most MCP clients.
Authentication Method
This server uses X-Session-Token authentication with the Notehub API. You will need to provide your Notehub username (email) and password when using the tools. The server will automatically:
- Obtain a session token using the
/auth/login
endpoint - Cache the token for up to 29 minutes (tokens expire after 30 minutes)
- Automatically handle token refreshing when needed
Connecting to an MCP Client
Claude for Desktop (macOS/Windows)
- Install Claude for Desktop
- Update your Claude Desktop configuration file:
For macOS:
mkdir -p ~/Library/Application\ Support/Claude/
Edit or create ~/Library/Application Support/Claude/claude_desktop_config.json
:
{
"mcpServers": {
"notehub": {
"command": "python",
"args": [
"--directory",
"/path/to/your/mcp-server",
"run",
"notehub.py"
],
"availableTo": ["claude-3-opus-20240229", "claude-3-sonnet-20240229", "claude-3-5-sonnet-20240307", "claude-3-haiku-20240307"]
}
}
}
For Windows, the config file is located at:
%APPDATA%\Claude\claude_desktop_config.json
- Restart Claude for Desktop
Custom MCP Client
If you're building a custom MCP client, you'll need to:
- Start this server as a child process
- Communicate with it using stdin/stdout following the MCP protocol
- Configure your client to discover the tools this server exposes
Available Tools
This MCP server exposes the following tools:
get-projects
- Get all accessible Notehub projectsget-project-devices
- Get all devices for a specific project (with optional filtering)get-project-events
- Get all events for a specific project (with optional filtering)send-note
- Send a note to a specific device
Usage Examples
When using with Claude for Desktop, you can ask questions like:
- "Can you show me all my Notehub projects? My username is and my password is mypassword123"
- "Fetch all devices from my project app:12345 using my Notehub username () and password"
- "Get the last 10 events from device dev:12345 in project app:12345"
- "Send a note to device dev:12345 in project app:12345 with the following payload: {"message": "Hello from MCP"}"
Security Considerations
- This server requires your Notehub username and password to function.
- Never share your configuration file containing paths or credentials.
- The MCP protocol runs locally, so your credentials are not sent to remote servers.
- The server implements token caching for better performance while maintaining security.
- If your Notehub account was created using "Sign in with GitHub", you'll need to set a password in the Account settings panel in Notehub.io first.
Troubleshooting
If you encounter issues:
-
Check the logs for any error messages:
- macOS:
~/Library/Logs/Claude/mcp-server-notehub.log
- Windows:
%APPDATA%\Claude\Logs\mcp-server-notehub.log
- macOS:
-
Verify your Notehub credentials are correct.
-
If you signed up with GitHub, make sure you've set a password in your Notehub account settings.
-
Make sure the server is running with the correct Python version.
-
Ensure both
mcp
andnotehub_py
packages are properly installed.
Extending the Server
To add more capabilities to this server:
- Extend the functions with additional Notehub API features
- Register new tools with
@mcp.tool()
decorator - Add more filtering options to existing tools
- Implement additional error handling and reporting
License
MIT