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

Quick Start

1. Get Your API Token

1. Go to Sidvy

2. Sign up or log in to your account

3. Generate an API token from your account settings

4. Copy the JWT token

2. Install and Build

3. Set Up Environment

Create a .env file or set environment variables:

4. Configure Your AI Tool

Claude Desktop Configuration

Add to your claude_desktop_config.json:

Alternative using absolute path:

Claude Code Configuration

Add to your ~/.claude/settings.json (or project-level .claude/settings.json):

OpenAI ChatGPT Configuration

Add to your MCP configuration:

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

Install with OpenClaw

See the sidvy-skill repository for full documentation and manual installation.

Available Tools

Notes Management

• list_notes - List notes with filtering and search

• create_note - Create new markdown notes

• update_note - Edit note content and metadata

• delete_note - Move notes to trash

• search_notes - Full-text search across notes

• get_note - Retrieve specific note by ID

• get_recent_notes - Get recently updated notes

• append_to_note - Add content to existing notes

Groups Management

• list_groups - List groups with hierarchical structure

• create_group - Create new groups for organization

• update_group - Rename or move groups

• delete_group - Remove groups and children

• get_group_tree - Get complete group hierarchy

• get_root_groups - Get top-level groups

• get_child_groups - Get child groups of a parent

• get_group_path - Get the full path from root to a group

• move_group - Reorganize group structure

• create_group_path - Create nested group paths

Todos Management

• list_todos - List todos with filtering

• create_todo - Create new todos

• create_todos_for_note - Create multiple todos for a note at once

• update_todo - Edit todo text or status

• delete_todo - Remove todos

• toggle_todo - Switch completion status

• complete_todo / uncomplete_todo - Set completion state

• get_pending_todos - Get incomplete todos

• get_completed_todos - Get finished todos

• get_todos_for_note - Get todos for specific note

• get_todo_stats - Get completion statistics

• search_todos - Search todos by text content

Workspace Management

• list_workspaces - List all workspaces

• create_workspace - Create new workspace (max 2)

• update_workspace - Rename workspaces

• rename_workspace - Rename an existing workspace

• delete_workspace - Remove workspace and content

• get_workspace - Get workspace details

• get_default_workspace - Get user's default workspace

• get_workspace_by_name - Find a workspace by name

• get_workspace_stats - Get content statistics

• can_create_workspace - Check if another workspace can be created

• switch_workspace - Change active workspace

Calendar Management

• get_daily_note - Get a daily note for a specific date

• update_daily_note - Update a daily note's content

• append_to_daily_note - Append content to a daily note

• get_weekly_note - Get a weekly note for a specific week

• update_weekly_note - Update a weekly note's content

• append_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:

Development

Prerequisites

• Node.js 18+

• pnpm

Available Commands

Configuration 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

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

License

MIT License - see LICENSE file for details.