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

# 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"
      }
    }
  }
}

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"
  }
}

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

Workspace Management

• list_workspaces - List all workspaces
• create_workspace - Create new workspace (max 2)
• update_workspace - Rename workspaces
• delete_workspace - Remove workspace and content
• get_workspace - Get workspace details
• get_default_workspace - Get user's default workspace
• get_workspace_stats - Get content statistics
• switch_workspace - Change active workspace

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.