with-context-mcp

WithContext MCP Server

Let your AI coding agents write directly to your note-taking apps. WithContext provides project-scoped note management for AI agents working with Obsidian, enabling them to create documentation, track changes, and organize knowledge as they code.

Why WithContext?

Your AI coding agent needs a place to store documentation, meeting notes, and project updates. WithContext gives them direct access to your Obsidian vault with:

• Automatic Project Scoping - Each project gets its own folder, no cross-contamination
• Smart Editing - Agents can update frontmatter, replace sections, prepend/append content
• Session Tracking - Track what changes the agent makes with changelogs and todos
• Intelligent Organization - Built-in presets for keeping vaults clean
• Template System - Professional templates for consistent documentation

You set it up once. Your AI agent handles the rest.

Quick Setup

1. Install Obsidian REST API Plugin

• Open Obsidian Settings → Community Plugins → Browse
• Search for "Local REST API" and install
• Enable the plugin and copy your API key

2. Install WithContext

npm install -g with-context-mcp

3. Configure Your AI Client

Add this to your AI client's MCP configuration:

OpenCode (opencode.jsonc):

{
  "mcp": {
    "with-context": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "with-context-mcp"],
      "environment": {
        "OBSIDIAN_API_KEY": "{env:OBSIDIAN_API_KEY}",
        "OBSIDIAN_API_URL": "{env:OBSIDIAN_API_URL}",
        "OBSIDIAN_VAULT": "{env:OBSIDIAN_VAULT}",
        "PROJECT_BASE_PATH": "{env:PROJECT_BASE_PATH}",
      },
      "enabled": true,
    },
  },
}

Other Clients: Claude Desktop, Cline, Cursor, Windsurf, Continue.dev, GitHub Copilot →

4. Set Environment Variables

export OBSIDIAN_API_KEY="your_api_key_here"
export OBSIDIAN_API_URL="https://127.0.0.1:27124"
export OBSIDIAN_VAULT="MyVault"
export PROJECT_BASE_PATH="Projects"

That's it! Your AI agent now has access to 33+ tools for managing notes in MyVault/Projects/.

What Your Agent Can Do

Once configured, your AI coding agent can:

• Create and update documentation as it writes code
• Track changes with automatic changelogs and todos
• Organize the vault using intelligent presets
• Edit YAML frontmatter to add tags and metadata
• Search and update existing notes by content or filename
• Generate notes from templates for consistent formatting
• Replace specific sections in markdown files by heading

You don't need to learn the tools. Your AI agent will use them automatically when it needs to document something, track a change, or organize notes.

Example Workflow

When your AI agent works on a feature, it might:

• Start a session: start_session({ project_folder: 'my-app' })
• Create API docs: write_note({ path: 'docs/api.md', content: '...' })
• Track changes: add_changelog_entry({ type: 'feature', message: 'Add user API' })
• Add a todo: add_todo({ content: 'Write integration tests' })
• Update metadata: update_frontmatter({ path: 'docs/api.md', frontmatter: { status: 'draft' } })

Your vault automatically stays organized in:

MyVault/Projects/my-app/
├── docs/api.md
└── CHANGELOG.md

Documentation

Setup: Installation & Setup • Configuration

Reference: All Tools • Common Workflows • Sessions • Vault Organization

What's New in v3.0.6

• Prepend Mode - Add content to the beginning of notes
• update_frontmatter - Edit YAML frontmatter with merge/replace modes
• Fuzzy Finding - Quick file search with match highlighting
• replace_section - Edit specific markdown sections by heading

Full changelog →

Available Tools

Your AI agent has access to 33 tools across 6 categories:

Category	Tools
Core	write, read, list, search, delete, batch_write, get_metadata
Editing	update_frontmatter, replace_section
Sessions	start, pause, resume, end, status, changelog, todos, commit_suggestion
Organization	analyze_structure, generate_plan, reorganize
Config	setup, validate, preview, ingest, teleport, sync
Templates	list_templates, create_from_template

Detailed tool documentation →

Troubleshooting

Connection Issues? Ensure Obsidian is running, Local REST API plugin is enabled, and OBSIDIAN_API_URL matches the plugin port (default: 27124)

Authentication Failed? Verify OBSIDIAN_API_KEY from plugin settings and check for extra spaces

Path Errors? Use relative paths only (no ../ or absolute paths) - all paths are relative to your project folder

More help →

Security

• Project Scoping - Operations restricted to configured project folders
• Path Validation - Prevents directory traversal attacks
• HTTPS - Secure connection to Obsidian Local REST API
• API Key Authentication - Required for all operations

Contributing

Contributions welcome! Fork the repository, create a feature branch, add tests, and submit a pull request.

Contributing guidelines →

Links

npm: with-context-mcp • GitHub: boxpositron/with-context-mcp • Issues: Report bugs or request features

Made for AI coding agents and the humans who work with them