Vimango MCP Server

A Model Context Protocol (MCP) server that enables Claude Desktop to write markdown notes directly to the local vimango SQLite databases.

Overview

This MCP server allows Claude to create research notes and other content directly in your vimango note-taking application during conversations. It handles the database insertion logic, allowing seamless integration between Claude Desktop's research capabilities and your local note database.

Architecture

Database Structure

Vimango uses two separate SQLite databases:

vimango.db - Main database containing tasks/notes, contexts, folders, and keywords
fts5_vimango.db - Full-text search database (FTS5) for fast searching

Note Creation Workflow

MCP server creates new entry in task table without setting tid (left NULL until sync assigns it)
Entry includes: title, note body, folder_tid, context_tid, timestamps
FTS database is NOT touched - it will be updated during sync
When you sync vimango with the remote server:
- Server assigns real tid to entry
- Sync process updates local FTS database

This design keeps the MCP server simple and leverages vimango's existing sync machinery.

Installation

Prerequisites

Python 3.11 or higher
UV package manager
Vimango application with configured databases

Setup

# Clone or navigate to the repository
cd /home/slzatz/vimango_mcp

# Create virtual environment and install dependencies
uv sync

# Configure database paths
cp config.json.example config.json
# Edit config.json to point to your vimango databases

Configuration

Create a config.json file in the project root:

{
  "vimango": {
    "main_db": "/path/to/vimango.db",
    "fts_db": "/path/to/fts5_vimango.db"
  }
}

Usage

Running the MCP Server

uv run vimango-mcp

Claude Desktop Configuration

Add to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "vimango": {
      "command": "/path/to/vimango_mcp/.venv/bin/vimango-mcp"
    }
  }
}

Available MCP Tools

create_note - Create a new note with title and markdown body
list_contexts - List available contexts for note categorization
list_folders - List available folders for note organization

Development

Project Structure

vimango_mcp/
├── src/
│   └── vimango_mcp/
│       ├── __init__.py     # Package initialization
│       ├── server.py       # MCP server implementation
│       └── db.py          # Database operations
├── tests/                  # Test suite
├── pyproject.toml         # UV project configuration
└── README.md

Running Tests

uv run pytest

Notes

The MCP server creates notes with tid left NULL so the server can assign IDs during sync
FTS synchronization happens automatically during vimango's normal sync process
Concurrent access is handled by SQLite's locking mechanisms
Research notes are typically created in the "research" folder

License

MIT

vimango_mcp