Littlebird Obsidian MCP

A local-first MCP server and Codex skill pack for turning daily work context into routed Obsidian knowledge.

Modern work leaves context scattered across meeting notes, browser research, email, chat, task systems, and AI conversations. Littlebird can summarize a day, but a daily summary sitting in a Gmail draft is not a durable knowledge base. Obsidian can be that knowledge base, but only if the information is routed into the right notes instead of dumped into one giant raw log.

This project connects those pieces. It gives Codex a safe local MCP server for one Obsidian vault, plus skills for importing Littlebird daily context and searching the vault later as "global knowledge."

The intended workflow is:

Littlebird captures and drafts daily context
  -> Codex imports the draft
  -> known projects/people/tasks/decisions route into Obsidian notes
  -> unknown projects go to routing review
  -> later, Codex can search Obsidian for project memory

The goal is not to preserve raw activity dumps. The goal is to preserve useful working memory in the right places: daily notes, project notes, people notes, decisions, tasks, and open loops.

What It Does

• Connects an MCP client to one configured Obsidian vault.
• Imports Littlebird daily-context drafts from Gmail through a Codex skill.
• Routes known projects and companies into configured Obsidian notes.
• Sends unknown projects to routing review instead of creating random files.
• Keeps a small ingest ledger for duplicate protection.
• Discards raw Littlebird draft bodies by default after routing.
• Adds a reverse lookup skill so Codex can search Obsidian as "global knowledge."

How It Works

Littlebird Gmail draft
  -> Codex skill
  -> littlebird-obsidian-mcp
  -> routed Obsidian notes
  -> Gmail draft deleted only after successful write

Reverse lookup:

User asks "check global knowledge"
  -> Codex skill
  -> search/read Obsidian through MCP
  -> answer with note sources

Requirements

• macOS, Linux, or Windows with Node.js 20+
• An Obsidian vault stored on the local filesystem
• Codex with MCP support
• Gmail connector access if using the Littlebird Gmail draft workflow

Obsidian does not need to be open for filesystem writes, but you should use an existing vault path.

node_modules/ is not part of the repo. Dependencies are declared in package.json and installed locally with npm install or npm run setup:codex.

Quick Start For Codex

git clone <repo-url>
cd littlebird-obsidian-mcp
npm run setup:codex

The setup script:

• asks for your Obsidian vault path
• installs dependencies
• builds the MCP server
• creates local config/routing.json from config/routing.example.json
• registers the MCP server in ~/.codex/config.toml
• installs the included Codex skills into ~/.codex/skills

Restart Codex after setup.

Manual Setup

Install and build:

npm install
npm run build

Configure your MCP client with:

[mcp_servers.littlebird_obsidian]
command = "node"
args = ["/absolute/path/to/littlebird-obsidian-mcp/dist/index.js"]
startup_timeout_sec = 30

[mcp_servers.littlebird_obsidian.env]
OBSIDIAN_VAULT_PATH = "/absolute/path/to/your/Obsidian/Vault"
OBSIDIAN_WRITE_MODE = "create-append"
RAW_CAPTURE_RETENTION = "discard"
LITTLEBIRD_ROUTING_CONFIG_PATH = "/absolute/path/to/littlebird-obsidian-mcp/config/routing.json"

Install skills:

ln -s "/absolute/path/to/littlebird-obsidian-mcp/skills/littlebird-gmail-to-obsidian" "$HOME/.codex/skills/littlebird-gmail-to-obsidian"
ln -s "/absolute/path/to/littlebird-obsidian-mcp/skills/obsidian-global-knowledge" "$HOME/.codex/skills/obsidian-global-knowledge"

Restart Codex after changing MCP config or installing skills.

Configure Routing

Copy the example routing file:

cp config/routing.example.json config/routing.json

Edit config/routing.json:

{
  "projectRoutes": [
    {
      "aliases": ["Example Project", "Example App"],
      "path": "Projects/Example Project.md"
    },
    {
      "aliases": ["Example Company", "Example Co"],
      "path": "Companies/Example Company.md"
    }
  ],
  "peopleRoutes": [
    {
      "aliases": ["Example Person"],
      "path": "People/Example Person.md"
    }
  ]
}

Known aliases route into configured notes. Unknown project/company items are written to:

00_Inbox/Routing Review/

The skill should ask where those unknowns belong before deleting the source draft.

Included Skills

Littlebird Gmail To Obsidian

Prompt:

Use $littlebird-gmail-to-obsidian to find my Littlebird Gmail drafts and write them to Obsidian.

Behavior:

• searches Gmail drafts for Littlebird daily context
• processes all matching drafts oldest first
• writes routed knowledge through the MCP server
• falls back to old Obsidian triage notes if no Gmail draft exists
• deletes Gmail drafts only after successful routing and no unresolved review

Obsidian Global Knowledge

Prompt:

Use $obsidian-global-knowledge to check my global directory for Example Project context.

Behavior:

• searches relevant Obsidian notes
• reads the highest-signal matches
• answers with a concise synthesis
• cites vault-relative note paths

MCP Tools

• list_vault_folder
• search_notes
• read_note
• create_note
• append_to_note
• append_daily_note
• create_triage_entry
• ingest_littlebird_context
• process_littlebird_triage_note

Safety Model

The server:

• restricts all file access to one configured vault path
• rejects absolute tool-input paths
• rejects path traversal outside the vault
• does not expose general delete or move tools
• never overwrites existing notes with create_note
• keeps raw Littlebird drafts out of the vault by default
• keeps a small ingest ledger for auditability and duplicate detection
• only deletes stale triage notes through process_littlebird_triage_note

Gmail draft deletion is handled by the Codex skill, not the MCP server. The skill should delete a draft only when the ingest result succeeded and no routing review is needed.

Verify

Temp-vault smoke test:

npm run smoke:cli

Configured-vault MCP smoke test:

OBSIDIAN_VAULT_PATH="/absolute/path/to/your/Obsidian/Vault" npm run smoke

Tests:

npm run typecheck
npm test

Local Files And Privacy

Commit:

• .env.example
• config/routing.example.json
• src/**
• skills/**
• docs/**

Do not commit:

• .env
• config/routing.json
• Obsidian vault contents
• Gmail draft ids
• personal MCP client config
• generated build/test output

See docs/env-and-local-files.md and docs/permissions.md.