Content
# 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:
```text
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
```text
Littlebird Gmail draft
-> Codex skill
-> littlebird-obsidian-mcp
-> routed Obsidian notes
-> Gmail draft deleted only after successful write
```
Reverse lookup:
```text
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
```bash
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:
```bash
npm install
npm run build
```
Configure your MCP client with:
```toml
[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:
```bash
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:
```bash
cp config/routing.example.json config/routing.json
```
Edit `config/routing.json`:
```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:
```text
00_Inbox/Routing Review/
```
The skill should ask where those unknowns belong before deleting the source draft.
## Included Skills
### Littlebird Gmail To Obsidian
Prompt:
```text
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:
```text
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:
```bash
npm run smoke:cli
```
Configured-vault MCP smoke test:
```bash
OBSIDIAN_VAULT_PATH="/absolute/path/to/your/Obsidian/Vault" npm run smoke
```
Tests:
```bash
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](docs/env-and-local-files.md) and [docs/permissions.md](docs/permissions.md).
