obsidian-sheet-plus-mcp-server

v0.0.5

Published

18 days ago

Obsidian Sheet Plus MCP (Model Context Protocol) server that enables AI agents and development tools to interact with Obsidian spreadsheets. It provides a comprehensive suite of tools for reading, writing, and managing sheet data, acting as a bridge to th

Obsidian Sheet Plus MCP Server

Empower your AI agents and development tools with seamless Obsidian Sheet Plus integration!

An MCP (Model Context Protocol) server providing comprehensive access to your Obsidian Sheet Plus data. Enables LLMs and AI agents to read, write, and manage your sheets through the Obsidian Sheet Plus plugin API.

Built on a robust TypeScript foundation, this server follows a modular architecture with comprehensive error handling, logging, and security features.

🚀 Core Capabilities: Obsidian Sheet Plus Tools 🛠️

This server equips your AI with 13 specialized tools to interact with your Obsidian Sheet Plus data:

Overview

The Obsidian Sheet Plus MCP Server acts as a bridge, allowing applications (MCP Clients) that understand the Model Context Protocol (MCP) – like advanced AI assistants (LLMs), IDE extensions, or custom scripts – to interact directly and safely with your Obsidian Sheet Plus data.

Instead of complex scripting or manual interaction, your tools can leverage this server to:

Automate sheet management: Read sheet data, update content, and manage your Obsidian Sheet Plus workbooks programmatically.
Integrate Obsidian Sheet Plus into AI workflows: Enable LLMs to access and modify your spreadsheet data as part of their research, analysis, or reporting tasks.
Build custom Obsidian Sheet Plus tools: Create external applications that interact with your sheet data in novel ways.

This server provides a standardized, secure, and efficient way to expose Obsidian Sheet Plus functionality via the MCP standard. It achieves this by communicating with the Obsidian Sheet Plus plugin API running inside your Obsidian vault.

Features

Core Utilities

Logging: Structured, configurable logging with sensitive data redaction
Error Handling: Centralized error processing with standardized error types
Configuration: Environment variable loading with comprehensive validation
Input Validation: Uses zod for robust schema validation
Request Context: Tracking and correlation of operations via unique request IDs
Type Safety: Strong typing enforced by TypeScript and Zod schemas
Flexible Transport: Supports both stdio and HTTP transports

Obsidian Sheet Plus Integration

Direct API Integration: Communicates directly with the Obsidian Sheet Plus plugin
Comprehensive Toolset: 13 specialized tools for sheet manipulation
Safety Features: Robust error handling and input validation
Efficient Operations: Supports batch operations for better performance

Installation

Prerequisites

Obsidian: You need Obsidian installed
Obsidian Sheet Plus Plugin: Install and enable the Obsidian Sheet Plus plugin within your Obsidian vault
API Key: Configure an API key within the Obsidian Sheet Plus plugin settings
Node.js & npm: Ensure you have Node.js (v18+ recommended) and npm installed

Installation Methods

Method 1: Using npx (Recommended for AI Agents)

The easiest way to use this server with AI agents like Claude is through npx, which automatically downloads and runs the package:

npx obsidian-sheet-plus-mcp-server

Method 2: Global Installation

For frequent use, you can install the server globally:

npm install -g obsidian-sheet-plus-mcp-server

# Then run it anytime
obsidian-sheet-plus-mcp-server

Method 3: From Source

For development or customization:

# Clone the repository
git clone https://github.com/ljcoder2015/obsidian-sheet-plus-mcp-server.git
cd obsidian-sheet-plus-mcp-server

# Install dependencies
npm install

# Build the project
npm run rebuild

# Run the server
npm start

Configuration

MCP Client Settings

Add the following to your MCP client's configuration file (e.g., claude_desktop_config.json or cline_mcp_settings.json):

{
  "mcpServers": {
    "obsidian-sheet-plus-mcp-server": {
      "command": "npx",
      "args": ["obsidian-sheet-plus-mcp-server"],
      "env": {
        "OBSIDIAN_SHEET_PLUS_API_KEY": "YOUR_API_KEY_FROM_OBSIDIAN_SHEET_PLUS_PLUGIN",
        "OBSIDIAN_SHEET_PLUS_BASE_URL": "http://127.0.0.1:3000",
        "OBSIDIAN_SHEET_PLUS_VERIFY_SSL": "false"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Environment Variables

Connecting to Obsidian Sheet Plus API

Non-encrypted (HTTP) - Recommended:
- Enable "Non-encrypted (HTTP) Server" in plugin settings
- Use URL: http://127.0.0.1:3000

Usage

Example: Using with Claude

Once configured, Claude can use the MCP server to interact with your Obsidian sheets:

Human: Get data from the "Budget" sheet in my Obsidian workbook
Assistant: I'll help you get data from the "Budget" sheet. Let me use the Obsidian Sheet Plus tool to retrieve this information.

[Using tool: get_sheet_data]
[Parameters: {"sheetName": "Budget"}]

[Tool response: {
  "success": true,
  "data": [
    ["Category", "Amount"],
    ["Housing", 1500],
    ["Food", 400],
    ["Transportation", 300],
    ["Entertainment", 200]
  ],
  "message": "Sheet data retrieved successfully"
}]

Here's the data from your "Budget" sheet:

| Category | Amount |
| :------- | :----- |
| Housing | 1500 |
| Food | 400 |
| Transportation | 300 |
| Entertainment | 200 |

Example: Updating Sheet Data

Human: Update the "Budget" sheet to change Food to 450
Assistant: I'll help you update the "Budget" sheet. Let me use the Obsidian Sheet Plus tool to make this change.

[Using tool: set_sheet_data]
[Parameters: {
  "sheetName": "Budget",
  "range": "B3",
  "values": [[450]]
}]

[Tool response: {
  "success": true,
  "message": "Sheet data updated successfully"
}]

I've successfully updated the "Food" amount in your "Budget" sheet to 450.

Project Structure

The codebase follows a modular structure:

src/
├── index.ts           # Entry point: Initializes and starts the server
├── config/            # Configuration loading (env vars, package info)
├── mcp-server/        # Core MCP server logic
│   ├── server.ts      # Server setup and transport handling
│   ├── tools/         # MCP Tool implementations (13 tools)
│   └── transports/    # Stdio and HTTP transport logic
├── services/          # External API abstractions
│   └── obsidianSheetPlusRestAPI/ # Obsidian Sheet Plus API client
├── types-global/      # Shared TypeScript type definitions
└── utils/             # Common utility functions (logger, error handler, etc.)

Development

Build and Test

# Install dependencies
npm install

# Build the project (compile TypeScript)
npm run rebuild

# Start the server with stdio transport
npm run start:stdio

# Start the server with HTTP transport
npm run start:http

# Format code
npm run format

# Inspect server capabilities
npm run inspect:stdio

Adding New Tools

Create a new directory under src/mcp-server/tools/
Implement the tool logic, registration, and handler
Register the tool in src/mcp-server/server.ts

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.