Neemee Mcp

io.github.pbonnevillePublished by GitHub account pbonnevillev3.0.2Updated Oct 24, 2026

MCP client library and bridge for Neemee personal knowledge management system

VerifiedSTDIODesktop onlyProductivity & WorkflowKnowledge & Memory

Overview

AI-generated overview

A local bridge and TypeScript client that connects an assistant to the Neemee personal knowledge management system for notes and notebooks.

What you can do
Create, update, delete and search notes, with titles, source URLs, notebooks, frontmatter and tag or date filters. Create, update, delete and search notebooks. List notes and notebooks with paging and filters, and fetch a single note or notebook. Read system information such as usage statistics, health and recent activity. List the tools and resources the connected Neemee server exposes.
When to use it
Use it when your notes and research live in Neemee and you want an assistant to capture, find, organize or clean up notes and notebooks from a chat session. It suits Claude Desktop or other local MCP clients that need a STDIO bridge to a Neemee account.
Requirements
Runs locally as an npm package (neemee-mcp) over STDIO, requiring Node.js 18 or later. A Neemee API key is required, supplied as the NEEMEE_API_KEY environment variable or the --api-key argument. The optional NEEMEE_API_BASE_URL defaults to the hosted Neemee endpoint, so network access is needed.
Before you install
The API key grants access to your Neemee account; keep it out of shared configuration files and logs. Write operations create and update notes and notebooks, and delete operations remove them permanently, so use a read-scoped key unless changes are intended. Note content, searches and metadata are sent to the Neemee service at the configured base URL.

Installation

In SourceWeft

  1. Open Neemee Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Neemee MCP Client Library

A TypeScript client library for connecting to Neemee MCP servers using the official Model Context Protocol SDK.

Overview

This library provides a convenient interface for interacting with Neemee personal knowledge management systems through the Model Context Protocol (MCP). It supports both HTTP and STDIO transport modes and includes full TypeScript support.

Installation

bash
npm install neemee-mcp

Quick Start

HTTP Mode (Web Applications)

typescript
import { NeemeeClient } from 'neemee-mcp';
const client = new NeemeeClient({  transport: 'http',  baseUrl: 'https://neemee.app/mcp',  apiKey: 'your-api-key'});
await client.connect();
// Create a noteconst result = await client.tools.createNote({  content: 'My note content',  title: 'My Note'});
console.log(result);
await client.disconnect();

STDIO Mode (Direct Process Communication)

typescript
import { NeemeeClient } from 'neemee-mcp';
const client = new NeemeeClient({  transport: 'stdio'});
await client.connect();
// Use same API as HTTP modeconst notes = await client.resources.listNotes();console.log(notes);
await client.disconnect();

API Reference

NeemeeClient

Main client class that provides access to tools and resources.

Constructor Options
typescript
interface NeemeeClientOptions {  transport: 'http' | 'stdio';  baseUrl?: string;        // For HTTP mode  apiKey?: string;         // For authentication  timeout?: number;        // Request timeout in milliseconds}
Methods
  • connect(): Promise<void> - Connect to the server
  • disconnect(): Promise<void> - Disconnect from the server
  • listAvailableTools(): Promise<any> - List available MCP tools
  • listAvailableResources(): Promise<any> - List available MCP resources

Tools API

Access via client.tools:

Notes
typescript
// Create a noteawait client.tools.createNote({  content: 'Note content',  title: 'Optional title',  url: 'Optional source URL',  notebook: 'Optional notebook name',  frontmatter: { /* Optional metadata */ }});
// Update a noteawait client.tools.updateNote({  id: 'note-id',  content: 'Updated content',  title: 'Updated title'});
// Delete a noteawait client.tools.deleteNote('note-id', true);
// Search notesawait client.tools.searchNotes({  query: 'search terms',  notebook: 'notebook-name',  domain: 'example.com',  tags: 'tag1,tag2',  startDate: '2024-01-01',  endDate: '2024-12-31',  limit: 50});
Notebooks
typescript
// Create a notebookawait client.tools.createNotebook('Notebook Name', 'Optional description');
// Update a notebookawait client.tools.updateNotebook('notebook-id', 'New Name', 'New description');
// Delete a notebookawait client.tools.deleteNotebook('notebook-id', true);
// Search notebooksawait client.tools.searchNotebooks('search query', 20);

Resources API

Access via client.resources:

Notes
typescript
// List notes with filteringawait client.resources.listNotes({  page: 1,  limit: 20,  search: 'search terms',  domain: 'example.com',  notebook: 'notebook-name',  tags: 'tag1,tag2',  startDate: '2024-01-01',  endDate: '2024-12-31'});
// Get a specific noteawait client.resources.getNote('note-id');
Notebooks
typescript
// List notebooksawait client.resources.listNotebooks({  page: 1,  limit: 20,  search: 'search terms'});
// Get a specific notebookawait client.resources.getNotebook('notebook-id');
System Information
typescript
// Get usage statisticsawait client.resources.getStats();
// Check system healthawait client.resources.getHealth();
// Get recent activityawait client.resources.getRecentActivity();

Error Handling

The library provides specific error types for different failure scenarios:

typescript
import {   NeemeeClientError,  AuthenticationError,  ConnectionError,  NotFoundError,  ValidationError,  ServerError} from 'neemee-mcp';
try {  await client.connect();} catch (error) {  if (error instanceof AuthenticationError) {    console.error('Invalid API key');  } else if (error instanceof ConnectionError) {    console.error('Failed to connect to server');  } else if (error instanceof NeemeeClientError) {    console.error('Client error:', error.message);  }}

Migration from v1.x

Breaking Changes

  • Minimum Node.js version: Now requires Node.js 18.0.0+
  • Constructor options: Format has changed (see Quick Start examples)
  • Error types: Updated error hierarchy
  • Method signatures: Some parameters refined for better type safety

Migration Guide

Old v1.x Usage
typescript
// v1.x (deprecated)const client = new LegacyNeemeeClient({  useStdio: false,  serverUrl: 'https://api.example.com',  apiKey: 'key'});
New v2.x Usage
typescript
// v2.x (recommended)const client = new NeemeeClient({  transport: 'http',  baseUrl: 'https://api.example.com',  apiKey: 'key'});
Legacy Compatibility

For temporary compatibility, use the LegacyNeemeeClient:

typescript
import { LegacyNeemeeClient } from 'neemee-mcp';
// This provides the old API while you migrateconst client = new LegacyNeemeeClient({  useStdio: false,  serverUrl: 'https://api.example.com',  apiKey: 'key'});

Development

Building from Source

bash
git clone https://github.com/Paul-Bonneville-Labs/neemee-mcp.gitcd neemee-mcpnpm installnpm run build

Running Tests

bash
# Test client functionalitynpm run test:client
# Test legacy compatibilitynpm run test:legacy
# Run with mock API servernpm run test:mock-api

Available Scripts

  • npm run build - Compile TypeScript to dist/
  • npm run dev - Run development server with hot reload
  • npm run test:client - Test new client API
  • npm run test:legacy - Test legacy compatibility
  • npm run test:integration - Full integration tests

Examples

Complete Example with Error Handling

typescript
import { NeemeeClient, AuthenticationError, ConnectionError } from 'neemee-mcp';
async function example() {  const client = new NeemeeClient({    transport: 'http',    baseUrl: 'https://neemee.app/mcp',    apiKey: process.env.NEEMEE_API_KEY  });
  try {    await client.connect();        // Create a note    const createResult = await client.tools.createNote({      content: '# My First Note\n\nThis is some content.',      title: 'First Note',      frontmatter: {        tags: ['example', 'test'],        priority: 'high'      }    });        console.log('Created note:', createResult);        // Search for notes    const searchResult = await client.tools.searchNotes({      query: 'first',      tags: 'example',      limit: 10    });        console.log('Found notes:', searchResult);        // List available resources    const resources = await client.listAvailableResources();    console.log('Available resources:', resources);      } catch (error) {    if (error instanceof AuthenticationError) {      console.error('Authentication failed - check your API key');    } else if (error instanceof ConnectionError) {      console.error('Connection failed - check server URL and network');    } else {      console.error('Unexpected error:', error);    }  } finally {    await client.disconnect();  }}
example().catch(console.error);

Tag-Based Search

typescript
// Search notes with multiple tagsconst taggedNotes = await client.tools.searchNotes({  tags: 'work,important,urgent',  notebook: 'Projects',  limit: 25});
// List notes with specific tags via resourcesconst resourceNotes = await client.resources.listNotes({  tags: 'research,ai',  domain: 'arxiv.org',  limit: 50});

Configuration

Claude Desktop Configuration

Use this package as a local bridge for STDIO transport:

json
{  "mcpServers": {    "neemee-local": {      "command": "npx",      "args": ["-y", "neemee-mcp", "--api-key=your-api-key-here"],      "env": {        "NEEMEE_API_BASE_URL": "https://neemee.app/mcp"      }    }  }}

Authentication: Uses API key authentication. Get your API key from Neemee settings. The API key can be provided via the --api-key flag in the args or as a NEEMEE_API_KEY environment variable.

Environment Variables

  • NEEMEE_API_KEY - Your Neemee API key (required for STDIO mode)
  • NEEMEE_API_BASE_URL - Base URL for Neemee API (defaults to https://neemee.app/mcp)

Authentication Scopes

The client supports different permission levels based on your API key:

  • read: Access to resources and search operations
  • write: Create and update operations (includes read)
  • admin: Delete operations (includes write and read)

TypeScript Support

This library is written in TypeScript and provides full type definitions:

typescript
import type {   NeemeeClientOptions,  CreateNoteParams,  UpdateNoteParams,  SearchNotesParams } from 'neemee-mcp';
const options: NeemeeClientOptions = {  transport: 'http',  baseUrl: 'https://api.example.com',  apiKey: 'your-key'};
const noteParams: CreateNoteParams = {  content: 'Note content',  title: 'Note title',  frontmatter: {    tags: ['typescript', 'example'],    date: new Date().toISOString()  }};

License

MIT

Support

Source: README.md at commit 033bf9d

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v3.0.2LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.