flint-note

Flint Note MCP is an agent-first note-taking MCP server that serves local, markdown-based notes and exposes an MCP interface for AI clients. It orchestrates notes as structured content guided by per-note-type agent instructions, enabling AI agents to read schemas, create, update, and connect notes across vaults. The server emphasizes local storage, vault isolation, and cross-vault operations, so AI models can reason about notes without external dependencies. Key capabilities include intelligent note type handling, batch retrieval with get_notes, and optimized data transfer through field filtering to support large collections.

To use Flint Note, connect your MCP-capable client (e.g., Claude Desktop, Cursor, Raycast) to the running flint-note MCP server. In your client configuration, declare the flint-note server with the provided command and ensure your agent can access the agent instructions and metadata schemas defined for each note type. When creating or updating notes, always reference the agent instructions for the target note type, and utilize batch operations when working with multiple notes to improve performance and consistency. Remember to specify vault context (active vault or vault_id) for cross-vault workflows so the client routes actions to the intended storage location.

Common workflows include fetching multiple notes with get_notes (with field filtering to minimize payload), creating notes in bulk via batch create_note, and inspecting or updating note types using get_note_type_info and update_note_type. For best results, always check agent instructions before creating notes, populate necessary metadata, and include content_hash when updates to avoid conflicts. This server design encourages an agent-first approach to knowledge management, where AI agents guide data capture, organization, and cross-note connections.

Prerequisites:

• Node.js 18+ installed on your machine
• A client that supports MCP (e.g., Claude Desktop, Cursor, Raycast, etc.)

Installation steps:

1. Install Node.js 18+ from the official website or using your OS package manager.
2. Start the Flint Note MCP server using npx with the latest server package:

npx @flint-note/server@latest

3. Ensure the server starts successfully and is reachable on the default MCP endpoint configured by your client. If you need to pin to a specific version or run in a script, you can reference the npm package name in your automation.
4. In your MCP client configuration, add the Flint Note server entry as shown in the example:

{
  "mcpServers": {
    "flint-note": {
      "command": "npx",
      "args": ["@flint-note/server@latest"]
    }
  }
}

5. Optionally customize prompts and prompts directory in your client or server configuration if you are providing agent prompts for different models.

Notes:

• If you run behind a firewall or with restricted network, ensure the MCP endpoint used by your client is accessible.
• Since the project is described as unmaintained, exercise caution in production environments and consider for local experimentation or UI-focused exploration.

Tips and caveats:

• This MCP server stores notes locally as Markdown files; maintain file backups and consider versioning for critical data.
• The system is designed for agent-first interactions; ensure your AI agents understand the note-type schemas and metadata requirements to avoid inconsistent notes.
• For cross-vault workflows, use vault_id parameters rather than changing the active vault to keep vault isolation intact while enabling cross-vault operations.
• Always use get_note_type_info before creating any note to honor agent instructions and avoid creating non-conforming notes.
• When updating notes, include the content_hash to prevent conflicts; if a conflict occurs, the client should handle CONTENT_HASH_MISMATCH and reconcile changes.
• Leverage batch operations for efficiency when creating or updating multiple notes.
• If you encounter issues, check that your client is sending the appropriate fields (e.g., content_hash, vault_id) and that the local markdown storage is accessible and not corrupted.