yamos - yet another mcp obsidian server

you want your ai to be able to with your obsidian notes, right? remotely, right? via MCP, right? i gotchu

1. set up obsidian livesync to a couchdb server
2. connect yamos to the couchdb server
3. connect your ai to yamos via MCP
4. profit

tested with claude. ymmv with other ais. if it doesn't work with other ais then file an issue pl0x, if you are well-behaved maybe i will fix it

disclaimer

i'm a devops girlie, not a programmer by trade. this code might suck. it might also nuke your obsidian vault. it might also be insecure in some way i havent considered. i have tried my best while writing this, but at the end of the day please accept that you are using it at your own risk.

if your vault has been nuked by this, feel free to raise an issue, but i will not help you get your vault back. back your stuff up. ever heard of restic

features

mcp commands

• list_notes - list all notes in your vault, optionally filtered by path prefix

• read_note - read the content of any note

• write_note - create or update notes

• append_to_note - append content to existing notes

• insert_lines - insert content at a specific line number

• delete_lines - delete a range of lines from a note

• delete_note - remove notes from your vault

• batch_read_notes - read a bunch of notes in one go

• batch_write_notes - create/update multiple notes at once

• batch_delete_notes - nuke several notes

• batch_append_to_notes - append to multiple notes

all batch operations use partial success - if one note fails (bad path, doesn't exist, whatever), the others still go through. the error comes through in the json report to your litle ai guy

modes

• sse mode (default): run as a web service that ais can talk to!
• stdio mode: run as a subprocess for desktop ai clients, to talk to whatever your local obsidian client is talking to
  • there are other obsidian mcp servers which were purpose-built for this - if you'll be doing this exclusively i'd recommend using one of those instead.

todo

• find some loser out there to do a proper security audit
• cargo crate :)
• handle encrypted vaults
• support binary attachments (images and whatnot)

what you'll need

so before you get started, here's what you gotta have set up:

• a couchdb instance running somewhere with obsidian-livesync all configured
• obsidian on your various devices with the livesync plugin
• for sse mode: some way to expose the server to the internet, so that the ai provider's servers can talk to it
  • tailscale funnel works pretty well if you don't have your own public url

this sounds cool!!! how do i make it work

• install and configure it
• connect your ai to it (e.g. ,
  • claude: claude.ai → settings → connectors → add custom connector, put in your url and oauth credentials (oauth config)
• "hey ai could you use yamos to list my notes"

ERM HOW DOES IT WORK

if you dont care about the specifics and just want your little computer friend to look at your obsidian stuff, you can ignore this bit

1. the server connects to your couchdb instance (that's where obsidian-livesync stores all your vault data)
2. notes are stored using livesync's chunked format - content gets split into ~32 byte chunks stored as separate "leaf" documents
3. when you tell claude to modify a note through this mcp server, it writes the chunks to couchdb, and then livesync picks up the changes and syncs them to all your devices automatically
4. same thing in reverse - when you edit a note on any device, it syncs to couchdb, and then claude can see the changes

the document format

livesync uses chunked storage. the main document references chunks:

{
  "_id": "todo.md",
  "path": "todo.md",
  "children": ["h:abc123", "h:def456", "h:ghi789"],
  "ctime": 1640000000000,
  "mtime": 1640000000000,
  "size": 1234,
  "type": "plain",
  "eden": {}
}

each chunk is a separate document:

{
  "_id": "h:abc123",
  "data": "raw string content here",
  "type": "leaf"
}

http endpoints (sse mode)

mcp endpoints:

• POST / - streamable http endpoint for mcp protocol
  • from the spec docs, i couldn't really figure out whether this was expected to be / or /mcp or /sse. if anyone else can figure it out please let me know
  • i considered just making this endpoint the fallback, but that feels a little odd. but who knows, maybe that's normal

oauth endpoints:

• GET /.well-known/oauth-protected-resource - resource metadata (RFC 9728)
• GET /.well-known/oauth-authorization-server - auth server metadata (RFC 8414)
• GET /authorize - authorization endpoint (shows consent page)
• POST /token - token endpoint
• POST /register - dynamic client registration (RFC 7591)

she hack on my thing til i contribute

i use nix (btw) you should use nix it's real good if you dont use nix just do your usual rust cargo stuff like usual

# jump into the dev shell
nix develop

# run with debug logging to see what's going on
RUST_LOG=debug cargo run -- --transport sse

# run tests (if i ever write any lol)
cargo test

questions that i imagine would be frequently asked if anybody ever talked to me

why is static bearer auth implemented

i didnt bother to check whether claude supported it before i implemented it and then i discovered that claude doesnt supported it and then i repeatedly slammed my head into the desk and implemented oauth

your code sucks

yeah cry about it

help me set up livesync

no. perish

why rust

i am transgender

what are these nix files

i am transgender

why is this whole readme lowercase

i am transgender

ai is evil and uses lots of water

if you eat meat i'm here to remind you that animal agriculture uses far more

i want to support you

send me nice messages and tell me i'm pretty and tell me i have swag

license

mit - go cray! preferably morally good cray though. like crayfish cray

uhhh change da world! my final message: goodbye