Markup.ai MCP Server
A Model Context Protocol (MCP) server that integrates with the Markup.ai API to provide advanced text analysis and improvement capabilities to AI assistants like Claude and Cursor.
Features
- Text Rewriting: Automatically improve text for clarity, tone, and style guide compliance
- Content Analysis: Get detailed quality scores across multiple dimensions
- Writing Suggestions: Receive specific recommendations for text improvements
- Style Guide Support: AP, Chicago Manual of Style, Microsoft, and Proofpoint
- Multiple Dialects: American, British, Australian, and Canadian English
- Tone Flexibility: Academic, business, casual, conversational, formal, gen-z, informal, and technical
Installation
Prerequisites
- Node.js 18.0.0 or higher
- A Markup AI API key
Setup
- Clone the repository:
git clone https://github.com/markupai/mcp.git
cd mcp
- Install dependencies:
npm install
- Configure environment variables:
cp .env.example .env
# Edit .env and add your MARKUPAI_API_KEY
- Build the project:
npm run build
Configuration
| Variable | Required | Description | Default |
|---|---|---|---|
MARKUPAI_API_KEY | Yes | Your Markup.ai API key | - |
MARKUPAI_BASE_URL | No | API base URL | https://api.markup.ai |
DEBUG | No | Enable debug logging | false |
MAX_TEXT_LENGTH | No | Maximum text length (chars) | 100000 |
WORKFLOW_TIMEOUT | No | Workflow timeout (ms) | 60000 |
POLL_INTERVAL | No | Status check interval (ms) | 2000 |
MAX_RETRIES | No | API retry attempts | 3 |
Usage with AI IDEs
This MCP server is compatible with any IDE that supports the Model Context Protocol, including Claude Desktop and Cursor.
Configuration
The configuration is identical for all MCP-compatible IDEs. Only the configuration file location differs:
| IDE | Configuration File Location |
|---|---|
| Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json |
| Cursor (macOS/Linux) | ~/.cursor/mcp.json |
| Cursor (Windows) | %USERPROFILE%\.cursor\mcp.json |
Option 1: Run directly from GitHub (recommended)
Add this configuration to your IDE's MCP configuration file:
{
"mcpServers": {
"markupai": {
"command": "npx",
"args": [
"-y",
"github:markupai/mcp"
],
"env": {
"MARKUPAI_API_KEY": "your_api_key_here"
}
}
}
}
Option 2: Run from local installation
For local development or if you prefer to run from a local installation:
{
"mcpServers": {
"markupai": {
"command": "node",
"args": ["/path/to/mcp/dist/index.js"],
"env": {
"MARKUPAI_API_KEY": "your_api_key_here"
}
}
}
}
Note: After updating the configuration, restart your IDE for the changes to take effect.
Using with Cursor
When using this MCP server with Cursor, you'll see a "Calling undefined" message with a "Run tool" button when the AI wants to use Markup.ai tools. This is normal behavior - simply click "Run tool" to approve the analysis. This manual approval is Cursor's security feature for MCP tool execution.
Available Tools
markupai_rewrite
Automatically rewrite and improve text content.
Parameters:
text(required): The text to rewritedialect: Language dialect (default: "american_english")tone: Desired tone (default: "formal")style_guide: Style guide to follow (default: "microsoft")
markupai_check
Analyze text for quality issues without making changes.
Parameters:
text(required): The text to analyzedialect: Language dialect (default: "american_english")tone: Target tone to check against (default: "formal")style_guide: Style guide to check against (default: "microsoft")
markupai_suggestions
Get detailed editing suggestions for improving text.
Parameters:
text(required): The text to get suggestions fordialect: Language dialect (default: "american_english")tone: Target tone for suggestions (default: "formal")style_guide: Style guide for suggestions (default: "microsoft")
markupai_workflow_status
Check the status of an asynchronous workflow.
Parameters:
workflow_id(required): The workflow ID to checkworkflow_type(required): Type of workflow ("rewrites", "checks", or "suggestions")
Development
Running in Development Mode
npm run dev
Running Tests
# Test suggestions endpoint
node test-suggestions.js
# Test complete workflow
node test-suggestions-complete.js
Building
npm run build
Troubleshooting
Common Issues
-
"Calling undefined" message in Cursor: This is normal Cursor behavior, not an error. When you see this message with a "Run tool" button, click the button to execute the Markup.ai analysis. This is Cursor's security feature requiring manual approval for MCP tool execution.
-
"Client closed" error in Cursor: Try clearing the npx cache:
npx clear-npx-cacheand restart Cursor -
API key issues: Verify your
MARKUPAI_API_KEYis correctly set in the environment variables -
Permission errors: On Unix systems, ensure the compiled JavaScript file is executable (
chmod +x dist/index.js)
Debug Mode
Enable debug logging by setting DEBUG=true in your environment:
DEBUG=true npm run start
Architecture
The server implements the Model Context Protocol using stdio transport and provides four main tools that interact with the Markup.ai API. Key features include:
- Cross-IDE Compatibility: Works with Claude Desktop, Cursor, and any MCP-compatible IDE
- Retry Logic: Exponential backoff for improved reliability
- Timeout Handling: Configurable timeouts for long-running operations
- Comprehensive Logging: Debug mode for troubleshooting
- Type Safety: Full TypeScript implementation with proper type guards
- Graceful Shutdown: Proper cleanup on termination
License
MIT
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Run
npm run buildto ensure everything compiles - Submit a pull request
Support
For issues and questions:
- Create an issue on GitHub
- Check the Markup AI documentation
- Contact Markup.ai support