Skip to main content
Glama
erniomaldo

nc-forms-mcp

by erniomaldo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

nc-forms-mcp

MCP server for the Nextcloud Forms API v3. Create, update, clone, and validate forms — without ever leaking an app password into the agent's context.

Python MCP License

🤨 The Problem

Nextcloud Forms has a REST API at /ocs/v2.php/apps/forms/api/v3/ that uses HTTP Basic Auth with an app password. When an AI agent calls this API directly:

Issue

What happens

Consequence

Credential leakage

The password passes through the LLM's context

Stored in logs, prompt caches, conversation history

Tool sprawl

Every Forms operation is a raw curl invocation

Inconsistent error handling, no validation

No isolation

The same credential gets reused for WebDAV, shares, etc.

Scope creep — operations outside Forms API

Repetition

Auth headers, error parsing, and retry logic in every call

Wasteful tokens and fragile code

Bottom line: credentials in agent context = risk. Raw API calls in conversation = tech debt.

Related MCP server: Google Forms MCP

✅ The Solution

Wrap the Forms API in an MCP server that:

  1. Reads credentials from environment variables only — the agent never sees them

  2. Exposes 16 focused tools — forms_get, questions_add, options_update, etc.

  3. Runs as a stdio subprocess managed by the Hermes MCP client

  4. Returns structured JSON — no parsing needed

  5. Validates form health with a single tool call

┌──────────────┐   MCP stdio    ┌──────────────────┐   HTTPS Basic Auth   ┌──────────────────┐
│              │ ──────────────→│                  │ ────────────────────→│                  │
│  Hermes      │ ←──────────────│  nc-forms-mcp    │ ←────────────────────│  Nextcloud Forms  │
│  Agent       │                │  (Python process) │                     │  API v3          │
│              │                │  NC_FORMS_PASSWORD│                     │                  │
└──────────────┘                │  (env only,       │                     └──────────────────┘
                                │   never in chat)  │
                                └──────────────────┘

📦 Installation

Prerequisites

  • Python 3.10+

  • Nextcloud instance with Forms app (v5+)

  • Nextcloud app password (Settings → Security → Devices & sessions)

Install

git clone https://github.com/erniomaldo/nc-forms-mcp.git ~/Proyectos/nc-forms-mcp
cd ~/Proyectos/nc-forms-mcp

# Hermes uses its own venv — install there:
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python -e .

Or use your project's venv:

uv venv && uv pip install -e .

🔧 Hermes Configuration

Add to ~/.hermes/config.yaml:

mcp_servers:
  nc-forms:
    command: "uv"
    args:
      - "run"
      - "--directory"
      - "/home/ernesto-personal/Proyectos/nc-forms-mcp"
      - "nc-forms-mcp"
    env:
      NC_FORMS_USER: "erniomaldo"
      NC_FORMS_PASSWORD: "your-app-password-here"
      NC_FORMS_BASE: "https://base.agendasencilla.com"
    timeout: 30

Restart Hermes after adding. On startup it auto-discovers 16 tools prefixed mcp_nc_forms_*.

🛠️ Tools

Tool

What it does

Use case

forms_list

List all owned forms

Dashboard / overview

forms_get

Get full form with questions, options, shares

Read current state

forms_create

Create an empty form

Start a new brief/survey

forms_update

Update title, description, settings

Iterate on form metadata

forms_clone

Clone a form (no submissions)

V1 → V2 iteration

forms_delete

Permanently delete a form

Cleanup

questions_list

List all questions in a form

Overview

questions_get

Get a single question by ID

Check specific question

questions_add

Add a question (multiple choice, text, etc.)

Build form content

questions_update

Update question text, description, isRequired

Refine wording

questions_delete

Remove a question

Prune sections

questions_reorder

Reorder questions by ID array

Reorganize sections

options_add

Add options to a choice question

Populate answer choices

options_update

Update a single option's text

Fix typos

options_delete

Remove an option

Cleanup

forms_validate

Check all questions have valid optionTypes

QA before publishing

Tool naming

MCP prefix: mcp_nc_forms_ + tool name (underscores replace hyphens).

Example: mcp_nc_forms_forms_get → get form details.

🚀 Usage (after Hermes integration)

# List all forms
mcp_nc_forms_forms_list()

# Get form 8 with all questions + options
mcp_nc_forms_forms_get({ "form_id": 8 })

# Add a question to form 8
mcp_nc_forms_questions_add({
    "form_id": 8,
    "type": "multiple_unique",
    "text": "🎨 1.2 ¿Colores definidos?"
})

# Add options
mcp_nc_forms_options_add({
    "form_id": 8,
    "question_id": 74,
    "option_texts": ["✅ De acuerdo", "🟡 Cerca pero ajustes", "❌ No se parece"],
    "option_type": "choice"
})

# Validate before publishing
mcp_nc_forms_forms_validate({ "form_id": 8 })
# → {"healthy": true, "total_questions": 32, "issues": []}

🧪 CLI Testing (without Hermes)

export NC_FORMS_USER="erniomaldo"
export NC_FORMS_PASSWORD="your-app-password"
export NC_FORMS_BASE="https://base.agendasencilla.com"

nc-forms-mcp forms_list '{}'
nc-forms-mcp forms_get '{"form_id": 8}'
nc-forms-mcp forms_validate '{"form_id": 8}'

🏗️ Project Structure

nc-forms-mcp/
├── pyproject.toml          # Project metadata + dependencies
├── README.md               # This file
├── LICENSE
├── nc_forms_mcp/
│   ├── __init__.py         # Package init (re-exports server)
│   ├── server.py           # MCP server: auth, route, tools, entry points
└── tests/                  # Coming soon

🔐 Security

  • Credentials live in env config — the agent never sees NC_FORMS_PASSWORD

  • The app password is scoped to Forms API only — WebDAV, Shares, Calendar, Collectives, and other Nextcloud features use their own MCP tools with their own auth

  • Error messages redact credential-like patterns

  • The MCP server process inherits a filtered environment (Hermes strips secrets from the subprocess env except what you explicitly set in env)

What NOT to do

# ❌ WRONG — password leaks into agent context
mcp_servers:
  nc-forms:
    command: "python3"
    args: ["server.py", "--password", "TEZiJ-..."]
# ✅ CORRECT — password stays in env
mcp_servers:
  nc-forms:
    command: "uv"
    args: ["run", "--directory", "~/Proyectos/nc-forms-mcp", "nc-forms-mcp"]
    env:
      NC_FORMS_PASSWORD: "TEZiJ-..."

💡 Why not just use curl?

Approach

Secret leaks?

Inconsistent errors?

Token waste?

Reusable?

Raw curl in conversation

✅ Always

✅ Every call

✅ Headers + parsing

❌ No

Python script in /tmp

✅ In code

✅ Per script

✅ Duplicated logic

❌ Per task

MCP server

❌ Never

❌ Unified

❌ One setup

✅ All tasks

📋 Comparison with alternative approaches

nc-forms-mcp

Forms web UI

Direct REST API (curl)

Custom script

Setup

5 lines in config.yaml

Zero (browser)

Zero (curl installed)

Python + requests

Speed

Instant (stdio)

Point-and-click

Fast

Depends on quality

Repeatability

✅ Always same tools

❌ Manual clicks

❌ Varies per call

✅ If committed

Validation

✅ forms_validate built-in

❌ Manual review

❌ Never

❌ Rarely

CI/CD ready

✅ Yes

❌ No

⚠️ Needs auth wrapper

✅ If committed

Secret safety

✅ In env only

❌ Browser session

❌ In command args

⚠️ In code or env

Token cost

Low (one discovery)

N/A

High (per call)

Low (per script)

🔄 Related Projects

  • agentcheckpoint — atomic state store for multi-agent coordination (SQLite + MCP)

  • Hermes Agent — the personal AI agent that runs this MCP server

📄 License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers