Sidvy

You can run Sidvy MCP Server to give AI tools direct, secure access to Sidvy’s note-taking system. It enables full CRUD on notes, groups, todos, and workspaces with API key authentication and multi-workspace isolation, so your AI agents can manage content confidently and efficiently.

How to use

Start by securing an API token for authentication, then run the MCP server locally or connect to it from your AI tool. You can manage notes, groups, and todos across workspaces, search across content, and sync smart todos with markdown checklists. Use the server to drive AI-assisted organization, planning, and retrieval across your Sidvy data.

How to install

Prerequisites: Node.js 18+, pnpm installed.

1. Clone the project repository.

2. Install dependencies.

# 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 variables in a .env file or via your environment.

4. Start testing locally.

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

# Run the built server directly
node build/index.js

# Or use development mode if you prefer
pnpm run dev

Configuration and security

Environment variables control access and API routing. The server uses SIDVY_API_TOKEN for authentication and SIDVY_API_URL to target the Sidvy API. Enable debug logging with DEBUG if you need diagnostics.

If you expose the MCP server to AI tools, ensure tokens are kept secret and rotate them periodically. Prefer configuring tokens per environment (dev, staging, prod) and limit token scopes to what the AI tools require.

Usage with MCP clients

Configure your MCP client to connect via the provided local or remote run methods. With a local stdio setup, you run the node process and pass the script path to the built index as an argument. With a remote HTTP setup, you would point the client to the MCP server URL if provided (not shown here). You’ll typically supply SIDVY_API_TOKEN and SIDVY_API_URL through the client’s environment.

Example usage scenarios

Ask your AI tool to create a new note named “Meeting Notes” with a to-do list, or search for notes containing a keyword and return the most recently updated items. Create hierarchical groups to reflect project structures like “Projects/Web Development/Frontend” and attach notes and todos there.

Development

If you want to run in development mode, you can use hot-reload workflows and start the built server when ready.

Available tools

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 a note by ID

get_recent_notes

Get recently updated notes

append_to_note

Append content to an existing note

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

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

Set completion state to complete

uncomplete_todo

Set completion state to incomplete

get_pending_todos

Get incomplete todos

get_completed_todos

Get finished todos

get_todos_for_note

Get todos for a specific note

get_todo_stats

Get completion statistics

list_workspaces

List all workspaces

create_workspace

Create a new workspace (max 2)

update_workspace

Rename a workspace

delete_workspace

Remove a workspace and its 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