Knowledge-to-Action MCP

Turn Obsidian notes into agent-ready context, preview-only plans, and safe repo handoffs.

knowledge-to-action-mcp is an MCP server for people whose real project context lives in notes, decisions, roadmaps, and meeting docs, not just code.

Most Obsidian MCP servers stop at "read a note" or "search a vault."

This one goes further:

notes -> retrieval -> context packet -> action plan -> repo handoff

That means an MCP client can move from:

"open this markdown file"

to:

"understand the note, pull nearby context, summarize risks,
propose next steps, and show which repo files probably matter"

Why It Matters

If you work out of Obsidian, your important context is usually spread across:

roadmap notes
meeting notes
decisions
linked references
repo assumptions

Normal note integrations make an agent read those files.

knowledge-to-action-mcp helps an agent recover the surrounding context and turn it into something actionable without exposing a general shell runner.

What Makes It Different

Capability	Typical vault MCP	`knowledge-to-action-mcp`
Read notes	Yes	Yes
Search notes	Yes	Yes
Follow links / backlinks	Sometimes	Yes
Graph-aware context recovery	Rarely	Yes
Optional embeddings	Rarely	Yes
Agent-ready context packet	No	Yes
Preview-only plan from note	No	Yes
Note-to-repo handoff	No	Yes
General shell access	Sometimes	No

1-Minute Quickstart

Install:

npm install @tac0de/knowledge-to-action-mcp

Run in graph-only mode:

OBSIDIAN_VAULT_ROOT="/path/to/vault" \
npx @tac0de/knowledge-to-action-mcp

Turn on optional embeddings and planning:

OBSIDIAN_VAULT_ROOT="/path/to/vault" \
EMBEDDINGS_ENABLED=true \
PLANNING_ENABLED=true \
OPENAI_API_KEY="..." \
npx @tac0de/knowledge-to-action-mcp

Then call:

context.retrieve
context.bundle_for_agent
action.plan_from_note
action.handoff_to_repo

What You Actually Get

1. Obsidian-aware retrieval

deterministic note listing, reading, and search
wikilink resolution
backlinks
shared-tag neighbors
graph-aware context recovery

2. Optional GraphRAG

When embeddings are enabled, retrieval becomes:

lexical + graph + semantic rerank

No external graph database is required.

3. Agent-ready context packets

context.bundle_for_agent returns a structured packet instead of dumping raw markdown into a prompt.

That packet includes:

brief
key facts
open questions
risks
related notes
repo hints

4. Preview-only action planning

action.plan_from_note turns a note into:

summary
goals
constraints
decisions
open questions
suggested actions
handoff prompt

It does not mutate files.

5. Safe repo handoff

action.handoff_to_repo connects note context to a workspace using:

bounded ripgrep queries
bounded git status
matched file suggestions

This is intentionally not a general-purpose shell runner.

Example Workflow

Imagine you have these notes:

roadmap/search.md
meetings/2026-03-07-search-review.md
decisions/search-scope.md

And a repo with:

src/search.ts
src/features/search/index.ts

This MCP can help an agent:

Retrieve nearby notes with search, backlinks, tags, graph neighbors, and optional embeddings.
Compress that note cluster into a structured context packet.
Turn the source note into a preview-only action plan.
Suggest likely repo files before any edit happens.

That jump from "read notes" to "prepare action safely" is the whole point.

Demo Assets

If you want something concrete before wiring your own vault:

sample vault notes live in examples/sample-vault/
example context.bundle_for_agent output lives in examples/sample-output/context.bundle_for_agent.json
example action.plan_from_note output lives in examples/sample-output/action.plan_from_note.json
example Claude Desktop config lives in examples/claude-desktop-config.json

Public Tools

Vault + Graph

vault.list_notes
vault.read_note
vault.search_notes
vault.get_metadata
graph.build
graph.get_neighbors
graph.get_backlinks
context.gather

Retrieval + Planning

embeddings.index_vault
context.retrieve
context.bundle_for_agent
action.plan_from_note
action.handoff_to_repo

Workspace Inspection

exec.list_capabilities
exec.rg_search
exec.list_dir
exec.git_status

Example Output

context.bundle_for_agent:

{
  "brief": "Implement search using the existing dashboard flow.",
  "source": "roadmap/search.md",
  "keyFacts": [
    "Title: Search",
    "Tags: roadmap,search"
  ],
  "openQuestions": [
    "Where is the current search entrypoint?"
  ],
  "risks": [
    "Assumption: repo layout may differ from note context"
  ],
  "repoHints": {
    "matchedFiles": [
      "src/search.ts",
      "src/features/search/index.ts"
    ],
    "suggestedQueries": [
      "Search",
      "search"
    ]
  }
}

action.plan_from_note:

{
  "source": "roadmap/search.md",
  "summary": "Implement search using the existing dashboard flow.",
  "goals": [
    "Ship dashboard search"
  ],
  "constraints": [
    "No mutation without explicit approval"
  ],
  "openQuestions": [
    "Where is the current search entrypoint?"
  ],
  "suggestedActions": [
    "Review matched repo files",
    "Resolve open questions before implementation"
  ],
  "generationMode": "deterministic"
}

Configuration

Required

OBSIDIAN_VAULT_ROOT

Optional embeddings

EMBEDDINGS_ENABLED=false
EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_SQLITE_PATH=.knowledge-to-action-mcp/index.sqlite
OPENAI_API_KEY=...

Optional planning

PLANNING_ENABLED=false
PLANNING_PROVIDER=openai
PLANNING_MODEL=gpt-4.1-mini

Optional workspace inspection

EXECUTION_ENABLED=false
EXECUTION_CAPABILITIES=workspace.search,workspace.inspect,workspace.git_status
EXECUTION_TIMEOUT_MS=5000
EXECUTION_MAX_OUTPUT_BYTES=32768

Install In MCP Clients

Example stdio config:

{
  "command": "npx",
  "args": ["-y", "@tac0de/knowledge-to-action-mcp"],
  "env": {
    "OBSIDIAN_VAULT_ROOT": "/path/to/vault"
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "knowledge-to-action": {
      "command": "npx",
      "args": ["-y", "@tac0de/knowledge-to-action-mcp"],
      "env": {
        "OBSIDIAN_VAULT_ROOT": "/path/to/vault"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "knowledge-to-action": {
      "command": "npx",
      "args": ["-y", "@tac0de/knowledge-to-action-mcp"],
      "env": {
        "OBSIDIAN_VAULT_ROOT": "/path/to/vault"
      }
    }
  }
}

Security Boundary

This package is designed to be useful without turning into a local shell bomb.

vault access is read-only
plan generation is preview-only
embeddings are optional and local
repo inspection is bounded to the configured working directory
no generic bash.exec or arbitrary command tool is exposed

Good Fit

Use this project if you want:

Obsidian-native GraphRAG
note-to-action workflows for agents
structured context instead of giant markdown dumps
repo-aware handoff without broad execution access

Not Trying To Be

a general purpose agent runtime
a write-enabled automation framework
a hosted knowledge platform
a vector database product

Compatibility

package name: @tac0de/knowledge-to-action-mcp
legacy CLI alias: obsidian-mcp
Node.js 20+

Status

v2.1.1 is usable now:

typecheck passes
unit and integration tests pass
npm pack dry-run passes

The project is still early, but the main workflow is already working.

License

MIT

@tac0de/knowledge-to-action-mcp

Quick Install