Parse MCP Server 🗄️

An MCP (Model Context Protocol) server that enables AI agents to interact with Parse Server instances. Explore databases, query classes, troubleshoot issues, and safely modify data through natural language.

By Eliott Guillaumin

Features

🔍 Database Exploration - Discover schemas, classes, and relationships
📊 Querying - Full Parse query support with filters, sorting, pagination
🔗 Relations - Query and manage Pointer and Relation fields
✏️ CRUD Operations - Create, read, update, delete objects (with safety prompts)
📦 Batch Operations - Bulk create, update, and delete
☁️ Cloud Functions - Execute Parse Cloud Code
📈 Aggregation - MongoDB-style aggregation pipelines
🔐 Roles & Users - Query users and roles
🛡️ Safety First - Built-in prompts to ask permission before modifications

Quick Start

Prerequisites

Node.js 18+ (or Docker)
A Parse Server instance with valid credentials

Installation

# Clone the repository
git clone https://github.com/R3D347HR4Y/parse-mcp.git
cd parse-mcp

# Install dependencies
npm install

# Build
npm run build

Or use Docker (recommended):

docker pull purpleshow/parse-mcp-server:latest

Environment Variables

Parse Server Configuration

Variable	Required	Description
`PARSE_SERVER_URL`	✅	Parse Server URL (e.g., `https://parseapi.back4app.com`)
`PARSE_APP_ID`	✅	Your Parse Application ID
`PARSE_MASTER_KEY`	⚠️	Master Key for admin operations (schema access, config)
`PARSE_JS_KEY`	❌	JavaScript Key (optional)
`PARSE_REST_KEY`	❌	REST API Key (optional)

MCP Transport Configuration

Variable	Default	Description
`MCP_TRANSPORT`	`http`	Transport mode: `http` or `stdio`
`MCP_PORT`	`3000`	HTTP server port (only for HTTP transport)
`MCP_HOST`	`0.0.0.0`	HTTP server host (only for HTTP transport)

⚠️ Important: The Master Key grants full access to your database. Only use it when necessary and never expose it publicly.

Setup Guides

HTTP Mode (Default - Recommended for Remote/Docker)

The server runs as an HTTP server by default, making it easy to deploy remotely or in containers.

# Start the HTTP server (default port 3000)
PARSE_SERVER_URL="https://your-server.com/parse" \
PARSE_APP_ID="your-app-id" \
PARSE_MASTER_KEY="your-master-key" \
npm start

# Or specify a custom port
MCP_PORT=8080 npm start

The server exposes:

POST /mcp - MCP Streamable HTTP endpoint
GET /mcp - SSE stream for server-sent events
DELETE /mcp - Session termination
GET /health - Health check endpoint

Cursor IDE (stdio mode)

For local Cursor IDE integration, use stdio mode. Add to your Cursor settings (.cursor/mcp.json):

{
  "mcpServers": {
    "parse": {
      "command": "node",
      "args": ["/path/to/parse-mcp-server/dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "PARSE_SERVER_URL": "https://your-parse-server.com/parse",
        "PARSE_APP_ID": "your-app-id",
        "PARSE_MASTER_KEY": "your-master-key"
      }
    }
  }
}

Claude Desktop (stdio mode)

Add to your Claude Desktop config (claude_desktop_config.json):

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "parse": {
      "command": "node",
      "args": ["/path/to/parse-mcp-server/dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "PARSE_SERVER_URL": "https://your-parse-server.com/parse",
        "PARSE_APP_ID": "your-app-id",
        "PARSE_MASTER_KEY": "your-master-key"
      }
    }
  }
}

Running Directly

# HTTP mode (default) - starts an HTTP server
PARSE_SERVER_URL="https://your-parse-server.com/parse" \
PARSE_APP_ID="your-app-id" \
PARSE_MASTER_KEY="your-master-key" \
node dist/index.js

# stdio mode - for local IDE integration
MCP_TRANSPORT=stdio \
PARSE_SERVER_URL="https://your-parse-server.com/parse" \
PARSE_APP_ID="your-app-id" \
PARSE_MASTER_KEY="your-master-key" \
node dist/index.js

Docker Deployment

Use the pre-built image from Docker Hub:

# Pull the image
docker pull purpleshow/parse-mcp-server:latest

# Run in HTTP mode (default) - exposes port 3000
docker run -d \
  -p 3000:3000 \
  -e PARSE_SERVER_URL="https://your-parse-server.com/parse" \
  -e PARSE_APP_ID="your-app-id" \
  -e PARSE_MASTER_KEY="your-master-key" \
  purpleshow/parse-mcp-server:latest

# The MCP server is now available at http://localhost:3000/mcp
# Health check: http://localhost:3000/health

Or build from source:

docker build -t parse-mcp-server .

Using Docker with stdio mode (for Cursor/Claude)

For local IDE integration via stdio:

{
  "mcpServers": {
    "parse": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "MCP_TRANSPORT=stdio",
        "-e",
        "PARSE_SERVER_URL=https://your-parse-server.com/parse",
        "-e",
        "PARSE_APP_ID=your-app-id",
        "-e",
        "PARSE_MASTER_KEY=your-master-key",
        "purpleshow/parse-mcp-server:latest"
      ]
    }
  }
}

Back4App Setup

For Back4App hosted Parse Server:

{
  "mcpServers": {
    "parse": {
      "command": "node",
      "args": ["/path/to/parse-mcp-server/dist/index.js"],
      "env": {
        "PARSE_SERVER_URL": "https://parseapi.back4app.com",
        "PARSE_APP_ID": "your-back4app-app-id",
        "PARSE_MASTER_KEY": "your-back4app-master-key",
        "PARSE_JS_KEY": "your-back4app-js-key"
      }
    }
  }
}

Find your keys in Back4App Dashboard → App Settings → Security & Keys.

Available Tools

Connection & Health

Tool	Description
`check_connection`	Verify Parse Server connection and health

Schema Exploration

Tool	Description
`get_all_schemas`	Get schemas for all classes (requires Master Key)
`get_class_schema`	Get schema for a specific class

Data Exploration

Tool	Description
`get_sample_objects`	Get sample objects from a class to understand data structure
`query_class`	Query objects with filters, sorting, pagination
`count_objects`	Count objects matching a query
`get_object_by_id`	Get a specific object by ID

Relations

Tool	Description
`query_relation`	Query objects in a Relation field
`add_to_relation`	Add objects to a Relation ⚠️
`remove_from_relation`	Remove objects from a Relation ⚠️

CRUD Operations

Tool	Description
`create_object`	Create a new object ⚠️
`update_object`	Update an existing object ⚠️
`delete_object`	Delete an object ⚠️ 🔴

Batch Operations

Tool	Description
`batch_create`	Create multiple objects ⚠️
`batch_update`	Update multiple objects ⚠️
`batch_delete`	Delete multiple objects ⚠️ 🔴

Users & Roles

Tool	Description
`query_users`	Query the _User class
`get_roles`	Get all defined roles
`get_role_users`	Get users in a specific role

Cloud Code

Tool	Description
`run_cloud_function`	Execute a Cloud Code function ⚠️

Aggregation

Tool	Description
`aggregate_class`	Run aggregation pipelines (requires Master Key)

Troubleshooting

Tool	Description
`validate_pointer`	Check if a pointer references a valid object
`find_orphaned_pointers`	Find broken pointer references in a class
`get_class_statistics`	Get statistics about a class

Configuration

Tool	Description
`get_config`	Get Parse Config values
`update_config`	Update Parse Config values ⚠️

Legend:

⚠️ = Modifies data (asks for permission)
🔴 = Destructive operation (extra caution)

Usage Examples

Exploring a Database

You: "What classes exist in this Parse database and what data do they contain?"

AI: Let me check the connection and explore the schema...
[Uses check_connection, get_all_schemas, get_sample_objects for each class]

Querying Data

You: "Find all users who signed up in the last 7 days and have verified their email"

AI: I'll query the _User class with those filters...
[Uses query_class with date and emailVerified constraints]

Troubleshooting

You: "Some of our Order objects seem to have broken user references"

AI: I'll scan the Order class for orphaned user pointers...
[Uses find_orphaned_pointers on the "user" field]

Safe Data Modification

You: "Update all products in category 'Electronics' to have a 10% discount"

AI: I found 47 products in the Electronics category. Here are some examples:
[Shows sample products]

Do you want me to proceed with updating all 47 products to add a 10% discount?

You: "Yes, go ahead"

AI: Updating products...
[Uses batch_update with user permission]

Recommended Workflow

When working with an unfamiliar database, the AI should follow this workflow:

Check Connection → check_connection
Get Schema Overview → get_all_schemas
Sample Key Classes → get_sample_objects for each relevant class
Understand Statistics → get_class_statistics for important classes
Query as Needed → query_class with appropriate filters
Ask Permission → Before any write operations

The AI has built-in prompts that guide it through this workflow and remind it to always ask permission before modifying data.

Query Syntax

The query_class tool supports Parse query syntax. Here are examples:

Basic Equality

{ "status": "active" }

Comparison Operators

{
  "score": { "$gt": 100 },
  "age": { "$gte": 18, "$lte": 65 }
}

Array Operations

{
  "tags": { "$in": ["featured", "sale"] },
  "category": { "$nin": ["deprecated", "hidden"] }
}

Logical Operators

{
  "$or": [{ "status": "active" }, { "featured": true }]
}

Pointer Matching

{
  "author": {
    "__type": "Pointer",
    "className": "_User",
    "objectId": "abc123"
  }
}

Regular Expressions

{
  "email": { "$regex": "@company\\.com$", "$options": "i" }
}

Field Existence

{
  "profilePicture": { "$exists": true }
}

Aggregation Pipeline

The aggregate_class tool supports MongoDB-style aggregation:

[
  { "$match": { "status": "completed" } },
  {
    "$group": {
      "_id": "$category",
      "total": { "$sum": "$amount" },
      "count": { "$sum": 1 },
      "avgAmount": { "$avg": "$amount" }
    }
  },
  { "$sort": { "total": -1 } },
  { "$limit": 10 }
]

Security Considerations

Master Key Protection: The Master Key bypasses all security. Only use when necessary.
Environment Variables: Never commit credentials to version control.
Permission Prompts: The AI is instructed to always ask before modifying data.
Audit Trail: Consider logging tool usage for compliance.
Least Privilege: If possible, use keys with limited permissions.

Troubleshooting

"Parse Server not initialized"

Check that PARSE_SERVER_URL and PARSE_APP_ID are set correctly.

"Master Key is required"

Schema and config operations require the Master Key. Add PARSE_MASTER_KEY to your environment.

"Object not found"

The objectId doesn't exist or you don't have permission to access it. Try with Master Key if appropriate.

Connection Errors

Verify the Parse Server URL is correct and accessible
Check if your network/firewall allows the connection
Ensure the keys are valid

Development

# Install dependencies
npm install

# Run in development mode (with hot reload)
npm run dev

# Build for production
npm run build

# Run built version
npm start

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT

Links

GitHub: https://github.com/R3D347HR4Y/parse-mcp
Docker Hub: https://hub.docker.com/r/purpleshow/parse-mcp-server

Related Projects

Parse Server - The open source backend
Parse JS SDK - JavaScript SDK for Parse
MCP Protocol - Model Context Protocol specification

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github/workflows		.github/workflows
scripts		scripts
src		src
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
env.example		env.example
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

R3D347HR4Y/parse-mcp

Folders and files

Latest commit

History

Repository files navigation

Parse MCP Server 🗄️

Features

Quick Start

Prerequisites

Installation

Environment Variables

Parse Server Configuration

MCP Transport Configuration

Setup Guides

HTTP Mode (Default - Recommended for Remote/Docker)

Cursor IDE (stdio mode)

Claude Desktop (stdio mode)

Running Directly

Docker Deployment

Using Docker with stdio mode (for Cursor/Claude)

Back4App Setup

Available Tools

Connection & Health

Schema Exploration

Data Exploration

Relations

CRUD Operations

Batch Operations

Users & Roles

Cloud Code

Aggregation

Troubleshooting

Configuration

Usage Examples

Exploring a Database

Querying Data

Troubleshooting

Safe Data Modification

Recommended Workflow

Query Syntax

Basic Equality

Comparison Operators

Array Operations

Logical Operators

Pointer Matching

Regular Expressions

Field Existence

Aggregation Pipeline

Security Considerations

Troubleshooting

"Parse Server not initialized"

"Master Key is required"

"Object not found"

Connection Errors

Development

Contributing

License

Links

Related Projects

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages