Sidvy MCP Server
The Sidvy MCP Server provides AI tools with comprehensive access to a note-taking system, enabling full CRUD operations and management of notes, todos, groups, workspaces, and calendar notes through secure API integration.
Notes Management: Create, read, update, append, delete, search, and filter markdown notes; list and sort by various criteria; manage deleted/trashed notes and view recent activity.
Hierarchical Organization (Groups): Create nested group structures with automatic path creation (e.g., "Projects/Web Dev/Frontend"); move, rename, and delete groups with cascade deletion; retrieve group trees, root groups, child groups, and full paths.
Todos Management: Create, update, delete, toggle, and track todos with markdown checkbox synchronization and line number tracking; filter by completion status, note, or workspace; search todos by content; get statistics and view pending/completed todos separately; bulk create multiple todos.
Workspace Management: Create up to 2 workspaces per user for content isolation; switch between workspaces; rename and delete with safety confirmations; get workspace statistics (note counts, group counts, todo metrics); find workspaces by name or get default workspace; check creation eligibility.
Calendar Integration: Access, update, and append to daily and weekly notes for specific dates with automatic calendar-based note management.
Advanced Features: Full-text search across notes with workspace filtering; flexible filtering and sorting on all operations; API key-based JWT authentication; real-time synchronization with the Sidvy platform; workspace-aware operations with automatic default workspace handling.
Integration: Works seamlessly with MCP-compatible AI tools like Claude Desktop, OpenAI ChatGPT, and others.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Sidvy MCP Server search for notes about project planning and show me the recent ones"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Sidvy MCP Server
A comprehensive MCP (Model Context Protocol) server that provides AI tools with full access to the Sidvy API - a powerful note-taking system with workspaces, groups, todos, and real-time synchronization.
Features
Full CRUD Operations: Complete access to notes, groups, todos, and workspaces
Authentication: API key-based authentication for secure access
Workspace Management: Multi-workspace support with user isolation
Hierarchical Groups: Organize notes in nested group structures
Smart Todos: Todo tracking with markdown checkbox synchronization
Search & Filter: Full-text search across notes and advanced filtering
Simple Setup: Direct Node.js execution, no complex packaging
Easy Integration: Works with Claude Desktop, OpenAI ChatGPT, and other MCP-compatible AI tools
Related MCP server: Streamline MCP
Quick Start
1. Get Your API Token
Go to Sidvy
Sign up or log in to your account
Generate an API token from your account settings
Copy the JWT token
2. Install and Build
# Clone the repository
git clone https://github.com/martinhjartmyr/sidvy-mcp.git
cd sidvy-mcp
# Install dependencies
pnpm install
# Build the server
pnpm run build3. Set Up Environment
Create a .env file or set environment variables:
SIDVY_API_TOKEN=your_jwt_token_here
SIDVY_API_URL=https://sidvy.com/api4. Configure Your AI Tool
Claude Desktop Configuration
Add to your claude_desktop_config.json:
{
"mcpServers": {
"sidvy": {
"command": "node",
"args": ["/path/to/sidvy-mcp/build/index.js"],
"env": {
"SIDVY_API_TOKEN": "your_jwt_token_here",
"SIDVY_API_URL": "https://sidvy.com/api"
}
}
}
}Alternative using absolute path:
{
"mcpServers": {
"sidvy": {
"command": "/path/to/sidvy-mcp/build/index.js",
"env": {
"SIDVY_API_TOKEN": "your_jwt_token_here",
"SIDVY_API_URL": "https://sidvy.com/api"
}
}
}
}Claude Code Configuration
Add to your ~/.claude/settings.json (or project-level .claude/settings.json):
{
"mcpServers": {
"sidvy": {
"command": "node",
"args": ["/path/to/sidvy-mcp/build/index.js"],
"env": {
"SIDVY_API_TOKEN": "your_jwt_token_here",
"SIDVY_API_URL": "https://sidvy.com/api"
}
}
}
}OpenAI ChatGPT Configuration
Add to your MCP configuration:
{
"name": "sidvy",
"command": ["node", "/path/to/sidvy-mcp/build/index.js"],
"env": {
"SIDVY_API_TOKEN": "your_jwt_token_here",
"SIDVY_API_URL": "https://sidvy.com/api"
}
}Agent Skill
A companion Sidvy Skill is available for AI agents that support the Agent Skills format (Claude Code, OpenClaw, etc.). The skill provides contextual instructions that help agents use the Sidvy MCP tools more effectively.
Install with skills CLI
npx skills add martinhjartmyr/sidvy-skillInstall with OpenClaw
openclaw skills add martinhjartmyr/sidvy-skillSee the sidvy-skill repository for full documentation and manual installation.
Available Tools
Notes Management
list_notes- List notes with filtering and searchcreate_note- Create new markdown notesupdate_note- Edit note content and metadatadelete_note- Move notes to trashsearch_notes- Full-text search across notesget_note- Retrieve specific note by IDget_recent_notes- Get recently updated notesappend_to_note- Add content to existing notes
Groups Management
list_groups- List groups with hierarchical structurecreate_group- Create new groups for organizationupdate_group- Rename or move groupsdelete_group- Remove groups and childrenget_group_tree- Get complete group hierarchyget_root_groups- Get top-level groupsget_child_groups- Get child groups of a parentget_group_path- Get the full path from root to a groupmove_group- Reorganize group structurecreate_group_path- Create nested group paths
Todos Management
list_todos- List todos with filteringcreate_todo- Create new todoscreate_todos_for_note- Create multiple todos for a note at onceupdate_todo- Edit todo text or statusdelete_todo- Remove todostoggle_todo- Switch completion statuscomplete_todo/uncomplete_todo- Set completion stateget_pending_todos- Get incomplete todosget_completed_todos- Get finished todosget_todos_for_note- Get todos for specific noteget_todo_stats- Get completion statisticssearch_todos- Search todos by text content
Workspace Management
list_workspaces- List all workspacescreate_workspace- Create new workspace (max 2)update_workspace- Rename workspacesrename_workspace- Rename an existing workspacedelete_workspace- Remove workspace and contentget_workspace- Get workspace detailsget_default_workspace- Get user's default workspaceget_workspace_by_name- Find a workspace by nameget_workspace_stats- Get content statisticscan_create_workspace- Check if another workspace can be createdswitch_workspace- Change active workspace
Calendar Management
get_daily_note- Get a daily note for a specific dateupdate_daily_note- Update a daily note's contentappend_to_daily_note- Append content to a daily noteget_weekly_note- Get a weekly note for a specific weekupdate_weekly_note- Update a weekly note's contentappend_to_weekly_note- Append content to a weekly note
Example Usage
With Claude Desktop
Once configured, you can ask Claude:
"Create a new note called 'Meeting Notes' with a todo list for today's agenda"
"Search for all notes containing 'project planning' and show me the recent ones"
"Show me all my pending todos across all workspaces"
"Create a group structure for 'Projects/Web Development/Frontend' and add a note there"
Command Line Testing
You can test the server directly:
# Set environment variables
export SIDVY_API_TOKEN="your_token_here"
# Run the built server
node build/index.js
# Or run in development mode
pnpm run dev
# The server will start and wait for MCP protocol messagesDevelopment
Prerequisites
Node.js 18+
pnpm
Available Commands
# Install dependencies
pnpm install
# Run in development mode with hot reload
pnpm run dev
# Build for production
pnpm run build
# Run built server
pnpm run start
# Clean build files
pnpm run cleanConfiguration Options
Environment Variables
SIDVY_API_TOKEN- Your JWT authentication token (required)SIDVY_API_URL- API base URL (default: https://sidvy.com/api)DEBUG- Enable debug logging (default: false)
API Rate Limits
The Sidvy API has reasonable rate limits for normal usage. The MCP server handles rate limiting gracefully and will retry requests when appropriate.
Contributing
Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request
License
MIT License - see LICENSE file for details.
Available Tools
42 toolsappend_to_noteC
Append content to an existing note
Inputs: id (required), content (required), workspaceId.
can_create_workspaceA
Check if the user can create another workspace (max 2 allowed)
Inputs: no named parameters.
complete_todoB
Mark a todo as completed
Inputs: todoId (required).
create_groupC
Create a new group for organizing notes
Inputs: name (required), workspaceId, parentId.
create_group_pathA
Create a nested group structure from a path (creates missing parent groups)
Inputs: path (required), workspaceId.
create_noteC
Create a new note with markdown content
Inputs: name (required), content, workspaceId, groupId.
create_todoC
Create a new todo associated with a note
Inputs: text (required), noteId (required), lineNumber (required), completed, +1 more.
create_todos_for_noteC
Create multiple todos for a note at once
Inputs: noteId (required), todoTexts (required), startingLineNumber, workspaceId.
create_workspaceA
Create a new workspace (max 2 workspaces per user)
Inputs: name (required).
delete_groupA
Delete a group and all its child groups (cascade delete)
Inputs: groupId (required).
delete_noteB
Delete a note (moves to trash)
Inputs: id (required).
delete_todoB
Delete a todo (soft delete)
Inputs: todoId (required).
delete_workspaceA
Delete a workspace and all its content (cannot delete default workspace)
Inputs: workspaceId (required), confirmDelete (required).
get_child_groupsB
Get all child groups of a specific parent group
Inputs: parentId (required), workspaceId.
get_completed_todosC
Get all completed todos
Inputs: workspaceId, limit.
get_default_workspaceB
Get the user's default workspace
Inputs: no named parameters.
get_group_pathC
Get the full path from root to a specific group
Inputs: groupId (required), workspaceId (required).
get_group_treeA
Get the hierarchical tree structure of all groups in a workspace
Inputs: workspaceId (required).
get_noteB
Get a specific note by ID
Inputs: id (required), workspaceId.
get_pending_todosC
Get all incomplete/pending todos
Inputs: workspaceId, limit.
get_recent_notesB
Get recently updated notes
Inputs: workspaceId, limit.
get_root_groupsC
Get all root-level groups (groups with no parent)
Inputs: workspaceId.
get_todos_for_noteC
Get all todos associated with a specific note
Inputs: noteId (required), workspaceId.
get_todo_statsB
Get statistics about todos (total, completed, pending, completion rate)
Inputs: workspaceId.
get_workspaceC
Get details of a specific workspace
Inputs: workspaceId (required).
get_workspace_by_nameB
Find a workspace by its name
Inputs: name (required).
get_workspace_statsC
Get detailed statistics for a workspace
Inputs: workspaceId.
list_groupsC
List groups with hierarchical structure and filtering
Inputs: workspaceId, parentId, search, sort, +1 more.
list_notesB
List notes with optional filtering and search capabilities
Inputs: workspaceId, groupId, search, isDeleted, +2 more.
list_todosC
List todos with filtering options (by completion status, note, etc.)
Inputs: workspaceId, noteId, completed, isDeleted, +3 more.
list_workspacesB
List all workspaces for the authenticated user with content counts
Inputs: includeStats.
move_groupC
Move a group to a new parent (or to root level)
Inputs: groupId (required), newParentId.
rename_workspaceC
Rename an existing workspace
Inputs: workspaceId (required), newName (required).
search_notesB
Search notes by content or title with full-text search
Inputs: query (required), workspaceId, limit.
search_todosC
Search todos by text content
Inputs: query (required), workspaceId.
switch_workspaceB
Switch context to a different workspace (for subsequent operations)
Inputs: workspaceId (required).
toggle_todoB
Toggle a todo's completion status (complete <-> incomplete)
Inputs: todoId (required).
uncomplete_todoC
Mark a todo as incomplete
Inputs: todoId (required).
update_groupC
Update a group's name or move it in the hierarchy
Inputs: groupId (required), name, parentId.
update_noteC
Update an existing note's content or metadata
Inputs: id (required), name, content, groupId.
update_todoC
Update a todo's text, completion status, or line number
Inputs: todoId (required), text, completed, lineNumber.
update_workspaceC
Update a workspace (currently only name changes supported)
Inputs: workspaceId (required), name.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 42 tools
Most tools have distinct purposes, but some overlap exists: 'complete_todo', 'toggle_todo', and 'uncomplete_todo' all manage todo completion status, which could cause confusion. Similarly, 'get_pending_todos' and 'list_todos' with filtering might overlap. However, descriptions clarify differences, and other tools like 'create_group' vs. 'create_group_path' are well-differentiated.
Tool names follow a highly consistent verb_noun pattern throughout, using snake_case uniformly. Verbs are clear and predictable (e.g., create_, get_, list_, update_, delete_, search_), with no mixing of conventions or chaotic naming. This makes the set easy to navigate and understand.
With 42 tools, the count is excessive for a note and todo management server, making it feel heavy and potentially overwhelming. A more focused set of 10-20 tools could cover the same domain without redundancy, as many tools (e.g., multiple todo status tools) could be consolidated into fewer, more versatile ones.
The tool surface provides comprehensive CRUD and lifecycle coverage for notes, todos, groups, and workspaces, with no obvious gaps. It includes creation, retrieval, updating, deletion, searching, and specialized operations like statistics and hierarchical management, ensuring agents can handle all core workflows without dead ends.
Maintenance
Related MCP Connectors
AI access to your aNotepad online notes: read, search, write, and organize via 22 tools.
Read, search and edit your Sidenote notepads, whiteboards and images with your sync key.
Turn your notes, links and conversations into a Living Brain your AI tools share and build on.
Governed memory and workspace for any AI: tasks, calendar, mail and pages, with per-action consent.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceEnables interaction with SiYuan Note through its API for comprehensive note management. Supports searching, creating, editing documents, managing notebooks, and daily notes operations through natural language commands.31 npm15Apache 2.0
- AlicenseBqualityBmaintenanceEnables AI assistants to access and manage Streamline tasks, notes, tags, and workspaces via a Supabase-powered backend. It supports full CRUD operations, allowing users to search, create, update, and organize their productivity data through natural language.17MIT
- AlicenseCqualityCmaintenanceEnables AI assistants to interact with SiYuan Note for comprehensive notebook management, document editing, and block-level content operations. It supports advanced features like full-text search and SQL queries via secure API integration.334 npm40ISC
- AlicenseBqualityDmaintenanceEnables AI assistants to create, read, update, and manage SiYuan notes, supporting notebook management, document operations, block editing, database attribute views, search, file operations, and export.1116 npm1MIT