# 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
1. MCP server creates new entry in `task` table without setting `tid` (left NULL until sync assigns it)
2. Entry includes: title, note body, folder_tid, context_tid, timestamps
3. **FTS database is NOT touched** - it will be updated during sync
4. 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](https://github.com/astral-sh/uv) package manager
- Vimango application with configured databases
### Setup
```bash
# 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:
```json
{
"vimango": {
"main_db": "/path/to/vimango.db",
"fts_db": "/path/to/fts5_vimango.db"
}
}
```
## Usage
### Running the MCP Server
```bash
uv run vimango-mcp
```
### Claude Desktop Configuration
Add to your Claude Desktop MCP settings:
```json
{
"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
```bash
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
