Marble MCP Server
Integrates with Supabase to store and manage learning prompts in a database, enabling the generation of shortened, shareable URLs for interactive learning slides on the Marble platform.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Marble MCP Server Create slides explaining the authentication flow in this app"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Marble MCP Server
An MCP (Model Context Protocol) server that generates learning project links for the Marble platform (withmarble.io). This server enables Claude Code to analyze codebases and suggest relevant learning projects with direct links to create them on Marble.
Features
Codebase Analysis: Analyzes your current codebase to understand technologies and patterns
AI-Generated Projects: Suggests relevant learning projects based on code analysis
Interactive Slides: Generate links to interactive learning slides based on your code
Marble Platform Integration: Generates properly formatted links to create projects on withmarble.io
Customizable: Specify topics, difficulty levels, and code context for tailored suggestions
Short URLs: Stores prompts in a database for clean, shareable links (optional)
Installation
Claude Code
Run claude mcp add marble npx marble-mcp-server --scope user.
Cursor
Modify your ~/.cursor/mcp.json to be like:
{
"mcpServers": {
"marble": {
"type": "stdio",
"command": "npx",
"args": [
"marble-mcp-server"
],
"env": {
}
}
}
}Augment Code
Go to the Augment Settings.
Under "Tools", scroll down until you find "MCP". Click the "Import from JSON" button.
Paste the following JSON snippet:
{
"mcpServers": {
"marble": {
"type": "stdio",
"command": "npx",
"args": [
"marble-mcp-server"
],
"env": {
}
}
}
}Usage
1. Suggest Learning Projects
Ask Claude Code to suggest projects for learning something in your codebase:
"I want to learn more about React hooks. Can you suggest some projects?"
"What are some projects I could build to learn the authentication patterns used here?"
"Suggest beginner projects for learning the database design in this app"Claude Code will:
Use the
suggest_learning_projectstoolAnalyze your codebase for relevant code
Generate 3 project ideas
Create Marble platform links for each project
2. Generate Interactive Learning Slides
Ask Claude Code to generate interactive slides to explain concepts in your codebase:
"Create slides explaining how React hooks work in this codebase"
"Generate slides about the authentication flow in this app"
"Make slides explaining the database schema"Claude Code will:
Use the
generate_slides_linktoolRead relevant code from your codebase
Create a comprehensive prompt with code examples
Save the prompt to the database (if configured)
Return a link to interactive slides on Marble
3. Generate Individual Project Links
You can also ask Claude Code to generate a link for a specific project:
"Generate a Marble link for a project about building a REST API with Express"Configuration
Environment Variables
The generate_slides_link tool requires the following environment variables:
SUPABASE_URL: Your Supabase project URL (required)SUPABASE_KEY: Your Supabase publishable key (required, starts withsb_publishable_...)Find it in: Supabase Dashboard → Settings → API → Project API keys
Note: The SUPABASE_URL and SUPABASE_KEY environment variables are required for the generate_slides_link tool to work. The tool will error if these are not configured.
Security: Use your Supabase publishable key (sb_publishable_...), not the service role or secret key. The publishable key is:
✅ Safe to use in CLIs, MCP servers, and public code
✅ Can be rotated independently without downtime
✅ Restricted by Row Level Security policies
✅ The modern, recommended approach (replaces the legacy anon JWT key)
Important: Use the publishable key (sb_publishable_...), not secret or service role keys. Benefits:
✅ Safe to expose in CLIs, scripts, and MCP servers
✅ Easy rotation without downtime
✅ Modern best practice (replaces legacy JWT-based anon key)
The publishable key is restricted by Row Level Security (RLS) policies and can only:
✅ Insert new prompts into
slide_prompts✅ Read prompts from
slide_prompts❌ Cannot update, delete, or access any other tables
Note: If these variables are not set, the generate_slides_link tool will return an error. The suggest_learning_projects and generate_marble_link tools do not require database configuration.
Database storage provides:
Creates shorter, more shareable URLs (e.g.,
withmarble.ai/learn?prompt_id=abc123)Avoids URL length limitations with long prompts
Improves link reliability across different platforms
If not provided, the server will fall back to encoding prompts directly in URLs.
Database Setup
If using Supabase integration, you'll need to create the slide_prompts table:
CREATE TABLE slide_prompts (
prompt_id UUID PRIMARY KEY,
prompt TEXT NOT NULL,
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
);Tools Provided
suggest_learning_projects
Instructs Claude Code to analyze the codebase and suggest learning projects.
Parameters:
topic(required): What to learn (e.g., "React hooks", "authentication")codeContext(optional): Specific files/directories to analyzedifficulty(optional): "Beginner", "Intermediate", or "Advanced"
Example:
{
"topic": "state management",
"codeContext": "src/store",
"difficulty": "Intermediate"
}generate_marble_link
Generates a Marble platform link from project data.
Parameters:
project(required): Project data object with:id: Unique ID (timestamp)title: Project titledescription: Detailed descriptioncategory: Primary language/frameworkdifficulty: "Beginner", "Intermediate", or "Advanced"timeEstimate: e.g., "2 hr", "90 min"technologies: Array of technologiestargetSkills: Array of skills to learn
Example:
{
"project": {
"id": 1701234567890,
"title": "Build a Task API",
"description": "Create a RESTful API for managing tasks with CRUD operations and authentication.",
"category": "Node.js",
"difficulty": "Intermediate",
"timeEstimate": "2 hr",
"technologies": ["Express", "MongoDB", "JWT"],
"targetSkills": ["REST APIs", "Authentication", "Database Design"]
}
}generate_slides_link
Generates a link to interactive learning slides on Marble.
Parameters:
query(required): A comprehensive prompt that includes:The main topic or concept to explain
Relevant code snippets from the codebase
Specific implementation details
Context about how the concept is used
Example:
{
"query": "Explain React hooks with examples from our codebase. Here's how we use useState in UserProfile.tsx: [code snippet]. Here's how we use useEffect in DataFetcher.tsx: [code snippet]. Focus on explaining the dependency array and cleanup functions."
}Returns: A markdown link like 🎓 [Learn: Explain React hooks...](https://withmarble.ai/learn?prompt_id=abc123)
Project Link Format
Generated links follow this format:
https://withmarble.io/projects/plan?projectData={urlEncodedJSON}The JSON structure includes all project metadata, which is decoded by the Marble platform to populate the project creation page.
Development
Watch Mode
npm run watchRebuild
npm run buildExample Interaction
User: "I want to learn about the React patterns used in this codebase"
Claude Code:
Uses
suggest_learning_projectswith topic "React patterns"Searches codebase for React components using Glob/Grep
Reads relevant files to understand patterns
Generates 3 project ideas:
Beginner: "Component Composition with Props"
Intermediate: "Custom Hooks for Data Fetching"
Advanced: "Compound Components Pattern"
Uses
generate_marble_linkfor each projectPresents projects with Marble links
Result: User gets 3 clickable links to create these projects on withmarble.io
How It Works
User asks for learning projects in Claude Code
MCP tool is invoked by Claude Code
Claude Code analyzes codebase using its file reading tools
Projects are generated based on code analysis
Links are created using the Marble platform URL format
User clicks link to start the project on withmarble.io
License
MIT
Available Tools
3 toolsgenerate_marble_linkB
Use this tool to generate Marble platform links for learning projects. Takes an array of 1-3 projects and returns markdown-formatted links (one per line) that can be inserted into project descriptions.
Inputs: projects (required).
generate_slides_linkA
Use this tool to generate a Marble platform link for interactive learning slides that EXPLAIN or TEACH concepts. Trigger this for ANY mention of: 'slides', 'marble slides', 'explain', 'teach me', 'show me', 'help me understand', 'how does X work', 'how is X done', 'how are X generated', 'walkthrough', 'tutorial', 'lesson', 'presentation', 'break down', 'give me an explanation', or similar explanation/teaching phrases. IMPORTANT: The query parameter must be LIMITED TO 6 PARAGRAPHS MAXIMUM. Before calling this tool, you should: 1) Read relevant code files from the codebase, 2) Analyze the code patterns and structure, 3) Summarize the most important context into 6 paragraphs or fewer. Focus on quality over quantity - include only the most relevant details. CRITICAL: After calling this tool, you MUST include the returned markdown link in your response to the user. The tool returns a clickable link - DO NOT just summarize or describe what the slides contain. Always show the actual link so the user can click it.
Inputs: title (required), query (required).
suggest_learning_projectsA
Use this tool when the user wants to PRACTICE or BUILD something to learn. Trigger this for ANY mention of: 'projects', 'marble projects', 'practice', 'exercises', 'build something', 'hands-on', 'try building', 'create a project', 'project ideas', 'what should I build', 'learn by doing', or similar learning-by-building phrases. This tool instructs the AI agent to: 1) Read relevant code from the codebase, 2) Analyze patterns and technologies used, 3) Generate project ideas that help learn those technologies, 4) Return formatted Marble platform links.
Inputs: topic (required), codeContext, difficulty.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: generate_marble_link creates links for existing projects, generate_slides_link creates links for explanatory slides, and suggest_learning_projects suggests new project ideas for practice. There is no overlap in functionality, and the descriptions clearly differentiate when to use each tool.
All tool names follow a consistent verb_noun pattern with snake_case: generate_marble_link, generate_slides_link, and suggest_learning_projects. The naming is predictable and readable throughout the set.
With only 3 tools, the server feels thin for a learning platform domain. While the tools cover key functions (linking projects, slides, and project suggestions), the scope might benefit from additional tools for managing or customizing learning content, making the count borderline for the apparent purpose.
The tool set covers core learning workflows: generating links for projects and slides, and suggesting projects for practice. However, there are minor gaps such as tools for updating or deleting links, tracking progress, or integrating with other learning resources, which agents might need to work around.
Related MCP Connectors
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.