Mew Control Protocol - A TypeScript client for the Mew API
npm install mew-mcpA sophisticated Model Context Protocol server that transforms Claude into a powerful cognitive partner for building and exploring knowledge graphs. This toolkit provides Claude with massive context loading, natural thinking capture, and intelligent knowledge navigation capabilities.
NEW: Mew MCP now offers Unix-like tools that mirror familiar filesystem commands for predictable, composable knowledge graph operations.
- Small, focused tools - Each tool does one thing well
- Predictable token usage - Know exactly what you get (navigation = IDs+titles, reading = full content)
- Composable operations - Chain tools together (find β cat)
- Familiar mental model - Unix commands developers already know
#### Navigation & Inspection
- mew_ls - List immediate children (IDs + titles only)
- Optional -l flag for metadata (childCount, hasChildren, updatedAt)
- Like: ls or ls -l
- mew_cat - Read single node's full content
- Like: cat file.txt
- mew_tree - ASCII tree hierarchy view
- Configurable depth (default: 3, max: 10)
- Like: tree -L 2
- mew_find - Search for nodes by content
- Returns IDs + titles only (no content dumps)
- Compose with mew_cat to read matches
- Like: find . -name "*.txt" | grep pattern
#### Modification
- mew_edit - Update node content directly
- No markdown parsing, just direct updates
- Like: vim file.txt
- mew_mv - Move node to new parent
- Automatic parent detection
- Like: mv file.txt new/location/
- mew_rm - Delete node (moves to recycle bin)
- Safe deletion, can be recovered
- Like: rm file.txt
- mew_mkdir - Create new node
- Like: mkdir new-folder
#### Relations
- mew_ln - Create semantic relation
- Like: ln -s (symbolic link)
- Common types: 'relates to', 'builds on', 'contradicts', 'enables'
Explore and read:
``bash`
mew_ls
mew_cat
mew_tree
Search and examine:
`bash`
mew_find "authentication" # Find nodes about auth
mew_cat
Create and organize:
`bash`
mew_mkdir
mew_edit
mew_mv
Build semantic web:
`bash`
mew_ln
mew_ln
The following tools remain in the codebase but are no longer registered in the MCP manifest (hidden from Claude). They may be removed in future versions if the Unix-like tools prove successful.
- Unified structure/content explorer with adaptive zoom levels and modes - Bulk reorganization tool for restructuring entire sections of your knowledge base - Natural thinking in markdown with unlimited hierarchies and custom relationship connectors - Create semantic connections between any nodes beyond hierarchical structure - Access different knowledge spaces (global, claude, user) with scope parameter / updateNode / deleteNode - Full CRUD operationsStep 1: Authenticate (one-time)
`bash`Login via browser - no CURRENT_USER_ID env var needed!
npx -y mew-mcp@latest login
This opens your browser to authenticate with Mew. Credentials are stored in ~/.mew-mcp/.
Step 2: Add to your config
Add to your claude_desktop_config.json:
`json`
{
"mcpServers": {
"Mew MCP": {
"command": "npx",
"args": ["-y", "mew-mcp@latest"],
"env": {
"BASE_URL": "https://mew-edge.ideaflow.app/api",
"BASE_NODE_URL": "https://mew-edge.ideaflow.app/",
"AUTH0_DOMAIN": "ideaflow-mew-dev.us.auth0.com",
"AUTH0_CLIENT_ID": "
"AUTH0_CLIENT_SECRET": "
"AUTH0_AUDIENCE": "https://ideaflow-mew-dev.us.auth0.com/api/v2/"
}
}
}
}
Legacy method: You can still use CURRENT_USER_ID env var instead of login if preferred.
Configuration locations:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%/Claude/claude_desktop_config.json
- Windows:
Other commands:
`bash`
npx -y mew-mcp@latest logout # Clear stored credentials
`bash`
git clone https://github.com/IdeaflowCo/mew-mcp.git
cd mew-mcp
npm install
Create .env file:`bash`
cp .env.example .env
Configure your .env:`dotenv`
BASE_URL=https://your-mew-api.example.com/api
BASE_NODE_URL=https://your-mew-app.example.com/
AUTH0_DOMAIN=your-instance.auth0.com
AUTH0_CLIENT_ID=your_client_id
AUTH0_CLIENT_SECRET=your_client_secret
AUTH0_AUDIENCE=your_api_audienceCURRENT_USER_ID is optional if you use: npm run start:mcp login
`bash`
npm run build
npm run start:mcp
method uses aggressive BFS (Breadth-First Search) expansion with intelligent limits:
- 12 levels deep maximum traversal
- 200 nodes per level breadth limiting
- 2000 total nodes safety cap
- Cycle detection prevents infinite recursion
- Graceful fallbacks ensure reliability$3
Tools like viewTreeContext use context-aware strategies:
- Global spaces: Prioritize breadth (wide but shallow)
- User spaces: Balanced approach (moderate depth/breadth)
- Specific nodes: Depth-first (narrow but deep)$3
claudeThinkTree recognizes natural connectors:
- β flows_to / β evidence: / β but:
- breakthrough: / tentative: / critical:
- actually: / hmm: / but wait:π± SMS, iMessage & Email Integration
Mew MCP includes an HTTP server for SMS, iMessage, email, and group chat integration:
$3
- π iMessage Integration (NEW!) - Real iMessage with blue bubbles, read receipts, and typing indicators via LoopMessage
- SMS Integration - 1:1 text conversations via Twilio (green bubbles fallback)
- Group Chat Support - Universal group SMS using Twilio Conversations API (works with any group size/participants)
- Email Integration - Email conversations via Mailgun with group email/Reply All support
- MMS Support - Send/receive images in both 1:1 and group chats
- Intelligent Routing - Automatically sends via iMessage when recipient supports it, falls back to SMS otherwise$3
1. Run the setup script to configure Twilio Conversations:
`bash
npx ts-node scripts/setup-conversations.ts
`2. Configure environment variables (see
.env.example):
`bash
TWILIO_ACCOUNT_SID=your_sid
TWILIO_AUTH_TOKEN=your_token
TWILIO_PHONE_NUMBER=+1234567890
TWILIO_CONVERSATIONS_SERVICE_SID=your_service_sid # From setup script
MAILGUN_API_KEY=your_key
MAILGUN_DOMAIN=your_domain
MAILGUN_FROM_EMAIL=mew@your-domain.com
`3. Deploy the HTTP server and configure webhooks in Twilio Console
$3
- GET /health - Health check (no auth) - shows enabled features
- POST /messages - Unified messaging - handles SMS (Twilio) + iMessage (LoopMessage) automatically
- POST /sms - Alias for /messages (backwards compatible)
- POST /conversations-webhook - Twilio Conversations webhook for group chats (signature verified)
- POST /email - Mailgun email webhook
- GET /sse - MCP server via SSE (API key required)π§ Environment Variables
$3
| Variable | Description | Required |
|----------|-------------|----------|
| BASE_URL | Mew API base URL | β
|
| BASE_NODE_URL | Node web interface base URL | β
|
| AUTH0_DOMAIN | Auth0 domain for authentication | β
|
| AUTH0_CLIENT_ID | Auth0 client identifier | β
|
| AUTH0_CLIENT_SECRET | Auth0 client secret | β
|
| AUTH0_AUDIENCE | Auth0 API audience | β
|
| CURRENT_USER_ID | User identifier (optional if using mew-mcp login) | β |$3
| Variable | Description | Required for HTTP |
|----------|-------------|-------------------|
| API_KEY | Authentication key for HTTP endpoints | β
|
| CLAUDE_API_KEY | Anthropic API key for SMS/email processing | β
|
| TWILIO_ACCOUNT_SID | Twilio account identifier | β
|
| TWILIO_AUTH_TOKEN | Twilio authentication token | β
|
| TWILIO_PHONE_NUMBER | Your Twilio phone number | β
|
| TWILIO_CONVERSATIONS_SERVICE_SID | Conversations service (from setup script) | β
|
| MAILGUN_API_KEY | Mailgun API key | β
|
| MAILGUN_DOMAIN | Mailgun sending domain | β
|
| MAILGUN_FROM_EMAIL | From email address for Mew | β
|
| PORT | Server port (default: 3000) | β |$3
| Variable | Description | Required |
|----------|-------------|----------|
|
LOOPMESSAGE_AUTH_KEY | LoopMessage authorization key | β
|
| LOOPMESSAGE_SECRET_KEY | LoopMessage secret key | β
|Sign up at loopmessage.com - $20.99/mo, sandbox for testing, pay only for delivered messages.
Note: If not configured, the system operates in SMS-only mode via Twilio.
π― Use Cases
For Researchers: Navigate vast literature graphs, connect ideas across domains, capture insights with natural relationship mapping.
For Writers: Build interconnected story worlds, track character relationships, organize research with semantic connections.
For Developers: Map codebase architectures, trace dependency relationships, document system knowledge with hierarchical thinking.
For Teams: Collaborative knowledge building, shared mental models, persistent institutional memory.
π OpenAI Function Calling
Mew MCP now supports OpenAI function calling, allowing you to use all 9 tools with OpenAI's API:
`typescript
import { createOpenAIAdapter } from 'mew-mcp/openai';// Create adapter with your config
const adapter = createOpenAIAdapter(config, userId);
// Use with OpenAI
const completion = await openai.chat.completions.create({
model: "gpt-4",
messages: messages,
tools: adapter.getFunctions().map(f => ({ type: 'function', function: f })),
tool_choice: 'auto'
});
// Execute function calls
if (completion.choices[0].message.tool_calls) {
for (const toolCall of completion.choices[0].message.tool_calls) {
const result = await adapter.execute({
name: toolCall.function.name,
arguments: toolCall.function.arguments
});
}
}
`All tools are available through the adapter with zero code duplication. See
examples/openai-usage.ts` for complete examples.- v3.11.0 - Added iMessage integration via Sendblue (blue bubbles, read receipts, typing indicators)
- v3.8.12 - Added OpenAI function calling support
- v1.1.45 - Complete cognitive toolkit with bulk operations
- v1.1.44 - Added semantic relationship creation
- v1.1.43 - Restored natural thinking and content preview tools
- v1.1.42 - Removed deprecated tools, fixed protocol issues
- v1.1.26 - Last stable version before feature development
We welcome contributions! This project represents cutting-edge human-AI cognitive collaboration. Whether you're improving algorithms, adding new cognitive tools, or enhancing the thinking capture mechanisms, your contributions help push the boundaries of augmented intelligence.
MIT License - see LICENSE.md for details.
---
Built for the future of human-AI cognitive partnership π€π§