{"id":30869661,"url":"https://github.com/blues/notehub_mcp_server","last_synced_at":"2026-01-17T12:01:27.566Z","repository":{"id":288949327,"uuid":"959555267","full_name":"blues/notehub_mcp_server","owner":"blues","description":"MCP Server Implementation of the Blues Notehub API","archived":false,"fork":false,"pushed_at":"2025-05-23T14:38:43.000Z","size":26,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-12-26T17:50:43.009Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blues.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-03T01:16:45.000Z","updated_at":"2025-05-23T14:38:47.000Z","dependencies_parsed_at":"2025-04-20T16:52:58.494Z","dependency_job_id":null,"html_url":"https://github.com/blues/notehub_mcp_server","commit_stats":null,"previous_names":["blues/notehub_mcp_server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/blues/notehub_mcp_server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blues%2Fnotehub_mcp_server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blues%2Fnotehub_mcp_server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blues%2Fnotehub_mcp_server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blues%2Fnotehub_mcp_server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blues","download_url":"https://codeload.github.com/blues/notehub_mcp_server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blues%2Fnotehub_mcp_server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28508464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T11:50:55.898Z","status":"ssl_error","status_checked_at":"2026-01-17T11:50:55.569Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-09-07T22:04:14.408Z","updated_at":"2026-01-17T12:01:27.508Z","avatar_url":"https://github.com/blues.png","language":"Python","funding_links":[],"categories":["🤖 AI/ML"],"sub_categories":[],"readme":"# Blues Notehub MCP Server (Python)\n\nThis 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.\n\n## What is MCP?\n\nModel 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.\n\n## Prerequisites\n\n- Python 3.8 or higher\n- A Blues Notehub account (https://notehub.io)\n- Your Notehub account username (email) and password\n\n## Installation\n\n### Option 1: Using pip (recommended)\n\n1. Clone or download this repository.\n2. Create a virtual environment:\n   ```bash\n   python -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   ```\n3. Install the dependencies:\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n### Option 2: Using uv (faster alternative)\n\n1. Install uv following the instructions at https://github.com/astral-sh/uv\n2. Create the environment and install dependencies:\n   ```bash\n   uv venv\n   source .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n   uv pip install -r requirements.txt\n   ```\n\n## Running the Server\n\nStart the server with:\n\n```bash\npython notehub.py\n```\n\nThe MCP server will run using stdio as the transport layer, which is the standard transport for most MCP clients.\n\n## Authentication Method\n\nThis 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:\n\n1. Obtain a session token using the `/auth/login` endpoint\n2. Cache the token for up to 29 minutes (tokens expire after 30 minutes)\n3. Automatically handle token refreshing when needed\n\n## Connecting to an MCP Client\n\n### Claude for Desktop (macOS/Windows)\n\n1. Install [Claude for Desktop](https://claude.ai/desktop)\n2. Update your Claude Desktop configuration file:\n\nFor macOS:\n```bash\nmkdir -p ~/Library/Application\\ Support/Claude/\n```\n\nEdit or create `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"notehub\": {\n      \"command\": \"python\",\n      \"args\": [\n        \"--directory\",\n        \"/path/to/your/mcp-server\",\n        \"run\",\n        \"notehub.py\"\n      ],\n      \"availableTo\": [\"claude-3-opus-20240229\", \"claude-3-sonnet-20240229\", \"claude-3-5-sonnet-20240307\", \"claude-3-haiku-20240307\"]\n    }\n  }\n}\n```\n\nFor Windows, the config file is located at:\n`%APPDATA%\\Claude\\claude_desktop_config.json`\n\n3. Restart Claude for Desktop\n\n### Custom MCP Client\n\nIf you're building a custom MCP client, you'll need to:\n\n1. Start this server as a child process\n2. Communicate with it using stdin/stdout following the MCP protocol\n3. Configure your client to discover the tools this server exposes\n\n## Available Tools\n\nThis MCP server exposes the following tools:\n\n1. `get-projects` - Get all accessible Notehub projects\n2. `get-project-devices` - Get all devices for a specific project (with optional filtering)\n3. `get-project-events` - Get all events for a specific project (with optional filtering)\n4. `send-note` - Send a note to a specific device\n\n## Usage Examples\n\nWhen using with Claude for Desktop, you can ask questions like:\n\n- \"Can you show me all my Notehub projects? My username is example@email.com and my password is mypassword123\"\n- \"Fetch all devices from my project app:12345 using my Notehub username (example@email.com) and password\"\n- \"Get the last 10 events from device dev:12345 in project app:12345\"\n- \"Send a note to device dev:12345 in project app:12345 with the following payload: {\"message\": \"Hello from MCP\"}\"\n\n## Security Considerations\n\n- This server requires your Notehub username and password to function.\n- Never share your configuration file containing paths or credentials.\n- The MCP protocol runs locally, so your credentials are not sent to remote servers.\n- The server implements token caching for better performance while maintaining security.\n- 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.\n\n## Troubleshooting\n\nIf you encounter issues:\n\n1. Check the logs for any error messages:\n   - macOS: `~/Library/Logs/Claude/mcp-server-notehub.log`\n   - Windows: `%APPDATA%\\Claude\\Logs\\mcp-server-notehub.log`\n\n2. Verify your Notehub credentials are correct.\n\n3. If you signed up with GitHub, make sure you've set a password in your Notehub account settings.\n\n4. Make sure the server is running with the correct Python version.\n\n5. Ensure both `mcp` and `notehub_py` packages are properly installed.\n\n## Extending the Server\n\nTo add more capabilities to this server:\n\n1. Extend the functions with additional Notehub API features\n2. Register new tools with `@mcp.tool()` decorator\n3. Add more filtering options to existing tools\n4. Implement additional error handling and reporting\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblues%2Fnotehub_mcp_server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblues%2Fnotehub_mcp_server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblues%2Fnotehub_mcp_server/lists"}