Skip to main content
Glama
Vault MCP Server

Vault MCP Server

by deceptikon

Vault MCP Server

A Model Context Protocol (MCP) server for interacting with the UniHub Vault - a file-based issue tracking and knowledge management system.

Quick Start

Prerequisites

  • Python 3.12+

  • uv package manager

Installation

uv sync

Running the Server

uv run python main.py

Configuration

Set the VAULT_PATH environment variable to point to your UniHub Vault directory:

export VAULT_PATH=/path/to/your/vault

Default locations (checked automatically if VAULT_PATH not set):

  • ./.unihub-vault/UniHubVault (relative to project root)

  • ~/Q/massage.kg/.unihub-vault/UniHubVault


Related MCP server: obsidian-mcp

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "vault": {
      "command": "uv",
      "args": ["run", "python", "/absolute/path/to/vault-mcp-server/main.py"],
      "env": {
        "VAULT_PATH": "/home/lexx/Q/massage.kg/.unihub-vault/UniHubVault"
      }
    }
  }
}

Cursor IDE

Add to .cursor/mcp.json in your workspace:

{
  "mcpServers": {
    "vault": {
      "command": "uv",
      "args": ["run", "python", "${workspaceFolder}/main.py"],
      "env": {
        "VAULT_PATH": "/home/lexx/Q/massage.kg/.unihub-vault/UniHubVault"
      }
    }
  }
}

Windsurf / Codeium

Add to your MCP settings:

{
  "vault": {
    "command": "uv",
    "args": ["run", "python", "/absolute/path/to/vault-mcp-server/main.py"],
    "env": {
      "VAULT_PATH": "/path/to/vault"
    }
  }
}

Generic MCP Client

{
  "vault": {
    "command": "python",
    "args": ["/absolute/path/to/vault-mcp-server/main.py"],
    "env": {
      "VAULT_PATH": "/path/to/vault"
    }
  }
}

Available Tools

Issue Management (5 tools)

Tool

Description

create_issue(name, body, tags?)

Create issue in 10_Inbox, returns 8-char ID

read_issue(iss_uniq_id)

Read issue content by unique ID

update_issue(iss_uniq_id, content, append?)

Update or append to issue

move_issue(iss_uniq_id, stage)

Move issue to stage (10_Inbox, 20_Processing, 30_ToReview, 999_Finished)

list_issues(stage?)

List issues in stage (default: 10_Inbox)

Vault Operations (3 tools)

Tool

Description

read_note(path)

Read any note from vault (path relative to vault root)

list_notes(directory?)

List markdown files in directory

search_vault(query)

Search all .md files (auto-detects regex vs keyword)

Status (1 tool)

Tool

Description

get_status()

Dashboard: issues by stage + recently modified notes

Telegram (3 tools)

Tool

Description

set_telegram_webhook(url)

Set bot webhook URL

check_telegram_webhook()

Check webhook status

poll_telegram_updates()

Poll and forward updates to local webhook


Issue Lifecycle

10_Inbox → 20_Processing → 30_ToReview → 999_Finished
   ↑            ↑              ↑
 create      move           move

Typical Workflow

1. create_issue("Bug in login", "Users can't login with SSO", ["bug", "auth"])
   → Returns: "a1b2c3d4"

2. list_issues("10_Inbox")
   → Shows new issue in inbox

3. read_issue("a1b2c3d4")
   → Returns full issue content

4. move_issue("a1b2c3d4", "20_Processing")
   → Moves to processing stage

5. update_issue("a1b2c3d4", "\n## Investigation\nChecked logs...", append=True)
   → Appends investigation notes

6. move_issue("a1b2c3d4", "30_ToReview")
   → Moves to review when done

7. get_status()
   → Shows overview of all stages

Stage Names

Both full and short names are supported:

Short

Full

inbox

10_Inbox

processing

20_Processing

review

30_ToReview

finished

999_Finished


Tool Examples

Create and Track an Issue

create_issue(name="Add dark mode", body="Users requested dark theme", tags=["feature", "ui"])
→ "f5e4d3c2"

read_issue("f5e4d3c2")
→ Full issue content

update_issue("f5e4d3c2", "\n## Notes\nPriority: high", append=True)
→ "Successfully appended to issue f5e4d3c2"

move_issue("f5e4d3c2", "processing")
→ "Moved issue f5e4d3c2 to 20_Processing"

Search and Read Notes

search_vault("authentication")
→ 50_Protocols/Auth.md:5: ## Authentication Flow
  20_Processing/<~15-nov~> abc123_login.md:12: User authentication fails...

read_note("50_Protocols/Auth.md")
→ Full protocol content

list_notes("50_Protocols")
→ Auth.md
   Security.md
   ...

Get Status Overview

get_status()
→ ## Vault Status Overview

   ### Issues by Stage

   **10_Inbox**: 3 issue(s)
     - <~15-nov~> abc123_login.md
     - <~16-nov~> def456_search.md
     - <~17-nov~> ghi789_ui.md

   **20_Processing**: 1 issue(s)
     - <~10-nov~> f5e4d3c2_dark_mode.md

   **30_ToReview**: 0 issue(s)

   **999_Finished**: 12 issue(s)
     ...

   ### Recently Modified Notes

     - 20_Processing/<~10-nov~> f5e4d3c2_dark_mode.md (0d ago, 2025-03-29)
     - 50_Protocols/Auth.md (2d ago, 2025-03-27)

Running Tests

uv run python test_issue_tools.py

This runs an integration test covering the full issue lifecycle.


Architecture

  • FastMCP server framework for MCP protocol handling

  • File-based storage using markdown files in stage directories

  • Path safety validation to prevent directory traversal

  • Telegram integration via bot token from backend/.env

Available Tools

12 tools
check_telegram_webhookA

Check Telegram bot webhook status.

Inputs: no named parameters. Returns: result

create_issueA

Create a new issue in the 10_Inbox directory.

Args:
    name: Short descriptive name for the issue.
    body: Detailed description of the issue.
    tags: Optional list of tags for categorization.

Returns:
    8-character unique issue ID.

Inputs: body (required), name (required), tags. Returns: result

get_statusA

Get an overview of vault status: issues by stage and recent notes.

Provides a quick dashboard showing:
- Issue count per stage with recent items
- Recently modified notes across the vault

Returns:
    Formatted status summary.

Inputs: no named parameters. Returns: result

list_issuesA

List all issues in a specific stage.

Args:
    stage: Stage folder name. One of:
           - "10_Inbox" or "inbox" (default)
           - "20_Processing" or "processing"
           - "30_ToReview" or "review"
           - "999_Finished" or "finished"

Returns:
    Newline-separated list of issue filenames.

Inputs: stage. Returns: result

list_notesA

List all markdown files in a directory.

Args:
    directory: Directory path relative to vault root.
               If None, lists root directory.

Returns:
    Newline-separated list of filenames.

Inputs: directory. Returns: result

move_issueA

Move an issue to a different stage.

Args:
    iss_uniq_id: 8-character unique issue ID.
    stage: Target stage folder name. One of:
           - "10_Inbox" or "inbox"
           - "20_Processing" or "processing"
           - "30_ToReview" or "review"
           - "999_Finished" or "finished"

Returns:
    Confirmation message with new location.

Inputs: stage (required), iss_uniq_id (required). Returns: result

poll_telegram_updatesB

Poll Telegram for updates and forward them to local webhook.

Inputs: no named parameters. Returns: result

read_issueA

Read an issue's content by its unique ID.

Args:
    iss_uniq_id: 8-character unique issue ID.

Returns:
    Full content of the issue file.

Inputs: iss_uniq_id (required). Returns: result

read_noteA

Read any note from the vault.

Args:
    path: Path relative to vault root (e.g., "50_Protocols/Auth.md").

Returns:
    Full content of the note.

Inputs: path (required). Returns: result

search_vaultA

Search through all .md files in the vault.

Auto-detects search type:
- If query contains regex metacharacters (.*+?^${}()|[]\), uses regex search.
- Otherwise, uses case-insensitive keyword search.

Args:
    query: Search term or regex pattern.

Returns:
    Matching lines in format: filepath:linenum: content

Inputs: query (required). Returns: result

set_telegram_webhookB

Set the Telegram bot webhook URL.

Inputs: url (required). Returns: result

update_issueA

Update an issue's content by its unique ID.

Args:
    iss_uniq_id: 8-character unique issue ID.
    content: New content to write or append.
    append: If True, appends to end of file; otherwise replaces entirely.

Returns:
    Confirmation message.

Inputs: content (required), iss_uniq_id (required), append. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 12 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose: issue CRUD and staging, note reading and listing, vault search, status overview, and three separate Telegram webhook operations (check, set, poll). No two tools overlap in function or could be confused for each other.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (create_issue, read_note, list_issues, set_telegram_webhook, etc.). The verb consistently leads, making the action obvious and the object clear, with no mixed conventions or ambiguous abbreviations.

    Tool Count5/5

    With 12 tools, the set is well-scoped for a vault management server. Each tool addresses a specific need in issue tracking, note access, search, and Telegram integration; none are redundant or excessive for the intended functionality.

    Completeness4/5

    The core issue lifecycle (create, read, update, move between stages, list) is complete, and note reading/searching is well covered. Minor gaps include the lack of an explicit delete operation for issues and no create/update/delete for notes, but these are likely intentional design choices for a vault-based workflow.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Enables interaction with multiple Obsidian vaults through natural language, supporting note operations, search, and vault management with both REST and filesystem backends.
      17
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables LLM clients to read, create, edit, delete, move, and search notes in local Obsidian vaults via direct filesystem access, including tag management and support for multiple vaults.
      22 PyPI
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables reading, writing, searching, and surgical editing of Obsidian vault notes, tags, and frontmatter, plus workspace control, vault structure management, and native Excalidraw automation.
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to search, read, and write notes in an Obsidian vault, including creating and updating notes in an inbox and syncing changes with Gitea/GitHub.
      MIT