Neemee Mcp

io.github.pbonneville由 GitHub 账号 pbonneville 发布v3.0.2更新于 Oct 24, 2026

MCP client library and bridge for Neemee personal knowledge management system

已验证STDIO仅桌面效率与工作流知识与记忆

概览

AI 生成的概览

一个本地桥接与 TypeScript 客户端，让助手连接 Neemee 个人知识管理系统，处理笔记与笔记本。

可以做什么
创建、更新、删除和搜索笔记，支持标题、来源网址、笔记本、frontmatter 以及标签和日期筛选。创建、更新、删除和搜索笔记本。分页并筛选地列出笔记与笔记本，获取单条笔记或单个笔记本。读取系统信息，如使用统计、健康状态和最近活动。列出所连接 Neemee 服务器提供的工具与资源。
适用场景
当你的笔记和研究资料存放在 Neemee，并希望助手在对话中记录、查找、整理或清理笔记和笔记本时使用。适合 Claude Desktop 等需要通过 STDIO 桥接访问 Neemee 账户的本地 MCP 客户端。
运行要求
以 npm 包 neemee-mcp 通过 STDIO 在本地运行，需要 Node.js 18 或更高版本。必须提供 Neemee API 密钥，可通过环境变量 NEEMEE_API_KEY 或 --api-key 参数传入。可选的 NEEMEE_API_BASE_URL 默认指向 Neemee 托管端点，因此需要网络访问。
安装前请注意
API 密钥可访问你的 Neemee 账户，请勿写入共享配置文件或日志。写操作会创建和更新笔记与笔记本，删除操作会永久移除它们，除非确需修改，否则请使用只读权限的密钥。笔记内容、搜索和元数据会发送到所配置基础网址的 Neemee 服务。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Neemee Mcp，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

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

来源：README.md，提交 033bf9d

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v3.0.2最新Sep 16, 2026

评分

已满足适用检查项的 40%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分

    请在仓库或注册中心条目中声明许可证。