Skip to main content
Glama
deceptikon

Vault MCP Server

by deceptikon
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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 Tools MCP Server

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

This server cannot be installed

F
license - not found
-
quality - not tested
D
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • jsoncanvas

    Create, validate, edit, export (markdown/svg/png/mermaid), and search JSON Canvas files.

  • sunub-obsidian-mcp-server

    Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…

  • Fresh Jots

    Read and write your Fresh Jots notes from Claude, Cursor, and any MCP client.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/deceptikon/vault-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server