Vault MCP Server
Provides tools for setting and checking Telegram webhooks, and polling updates to forward to a local webhook.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Vault MCP Server create a new issue for login bug"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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+
uvpackage manager
Installation
uv syncRunning the Server
uv run python main.pyConfiguration
Set the VAULT_PATH environment variable to point to your UniHub Vault directory:
export VAULT_PATH=/path/to/your/vaultDefault 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 in |
| Read issue content by unique ID |
| Update or append to issue |
| Move issue to stage ( |
| List issues in stage (default: |
Vault Operations (3 tools)
Tool | Description |
| Read any note from vault (path relative to vault root) |
| List markdown files in directory |
| Search all |
Status (1 tool)
Tool | Description |
| Dashboard: issues by stage + recently modified notes |
Telegram (3 tools)
Tool | Description |
| Set bot webhook URL |
| Check webhook status |
| Poll and forward updates to local webhook |
Issue Lifecycle
10_Inbox → 20_Processing → 30_ToReview → 999_Finished
↑ ↑ ↑
create move moveTypical 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 stagesStage Names
Both full and short names are supported:
Short | Full |
|
|
|
|
|
|
|
|
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.pyThis 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 toolscheck_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
Scored across 12 tools
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.
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.
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.
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
Related MCP Connectors
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Encrypted Markdown notes and team knowledge base. Search, read and write notes in vaults you allow.
Search, read and write the notes in the vaults you sync through Wander Cloud.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables interaction with multiple Obsidian vaults through natural language, supporting note operations, search, and vault management with both REST and filesystem backends.17-
- AlicenseNot gradedqualityCmaintenanceEnables 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 PyPIMIT
- AlicenseNot gradedqualityDmaintenanceEnables 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
- AlicenseNot gradedqualityCmaintenanceEnables 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