Skip to main content
Glama

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

  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

# Clone the repository
git clone https://github.com/martinhjartmyr/sidvy-mcp.git
cd sidvy-mcp

# Install dependencies
pnpm install

# Build the server
pnpm run build

3. Set Up Environment

Create a .env file or set environment variables:

SIDVY_API_TOKEN=your_jwt_token_here
SIDVY_API_URL=https://sidvy.com/api

4. 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-skill

Install with OpenClaw

openclaw skills add martinhjartmyr/sidvy-skill

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:

# 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 messages

Development

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 clean

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.

Available Tools

42 tools
append_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

    B3.3/5.0

    Scored across 42 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables 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 npm
      15
      Apache 2.0
    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      17
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      Enables 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.
      3
      34 npm
      40
      ISC
    • A
      license
      B
      quality
      D
      maintenance
      Enables 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.
      11
      16 npm
      1
      MIT