Matoroa Mcp

mataroa-mcp

An MCP server that lets you manage your Mataroa blog through natural language in Claude Desktop, Claude Code, or any MCP-compatible AI client.

---

What you can do

Tell Claude things like:

• "Show me all my blog posts"
• "Write a post about my weekend hike and save it as a draft"
• "Publish my sourdough post"
• "Are there any comments waiting for approval?"
• "Delete the draft called testing-123"
• "Create an About page for my blog"

Claude will call the right tool automatically.

---

Preview

---

Demo conversation link

Setup (5 minutes)

Option A: One-click install with the Claude Desktop extension (.mcpb)

1. Go to mataroa.blog and log in (or create a free account), then open Dashboard → API and copy your API key.
2. Download the latest mataroa-mcp.mcpb file from the Releases page.
3. Double-click the downloaded .mcpb file — Claude Desktop will open and prompt you to install the extension.
4. When prompted, paste your Mataroa API key into the configuration field.

That's it — no Python setup required. The rest of this guide covers manual setup (Option B) for Claude Code or advanced configurations.

---

Option B: Manual setup

1. Get your Mataroa API key

1. Go to mataroa.blog and log in (or create a free account).
2. Open Dashboard → API and copy your API key.

2. Install the server

You need Python 3.10 or later. The package is published on PyPI — install it with pip:

pip install mataroa-mcp

Or, if you have uv installed, you can skip the install step entirely and run the latest version on demand with uvx:

uvx mataroa-mcp

3. Add to Claude Desktop

Open your Claude Desktop config file:

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

If there is no "mcpServers" key, add it at the top level alongside any existing keys:

{
  "mcpServers": {
    "mataroa": {
      "command": "mataroa-mcp",
      "args": [],
      "env": {
        "MATAROA_API_KEY": "paste-your-key-here"
      }
    }
  },
  "...your other existing config keys...": "..."
}

If you used uvx instead of pip install, replace "command": "mataroa-mcp" and "args": [] with:

"command": "uvx",
"args": ["mataroa-mcp"]

4. Restart Claude Desktop

Quit and reopen Claude Desktop. You should see a small plug icon in the chat bar indicating MCP tools are active.

5. Test it

Type: "Show me my blog posts" — Claude should list them.

---

Add to Claude Code

Create or edit .mcp.json in your project root:

{
  "mcpServers": {
    "mataroa": {
      "command": "mataroa-mcp",
      "args": [],
      "env": {
        "MATAROA_API_KEY": "paste-your-key-here"
      }
    }
  }
}

> Replace "command": "mataroa-mcp", "args": [] with "command": "uvx", "args": ["mataroa-mcp"] if you installed via uvx instead of pip.

---

Available tools

| Tool | What it does | |------|-------------| | list_posts | List all posts (published + drafts) | | list_drafts | List only unpublished drafts | | get_post | Get a single post by slug | | create_post | Create a new post | | update_post | Edit an existing post | | delete_post | Permanently delete a post | | publish_post | Publish a draft (sets today's date, or a date you choose) | | unpublish_post | Revert a published post back to draft | | list_comments | List all comments (or just for one post) | | list_pending_comments | List comments awaiting moderation | | approve_comment | Approve a pending comment | | delete_comment | Delete a comment | | list_pages | List all pages | | get_page | Get a single page by slug | | create_page | Create a new page | | update_page | Edit an existing page | | delete_page | Permanently delete a page |

---

Notes

• API key is never stored in code — it's always read from the MATAROA_API_KEY environment variable.
• Mataroa has no rate limiting, so you can make requests freely.
• Blog-level settings (title, custom domain, etc.) are not accessible via the Mataroa API and therefore not exposed here.
• Draft posts have published_at: null. Publishing sets it to a date; unpublishing clears it.

---

Running tests

# Install test dependencies
pip install -e .
pip install pytest pytest-asyncio respx

# Unit tests (no API key needed)
python -m pytest tests/test_client.py tests/test_server.py -v

# Integration tests (requires a real Mataroa API key)
$env:MATAROA_API_KEY="your-key"; python -m pytest tests/test_integration.py --run-integration -v

Running the server locally

To test the server outside of Claude Desktop, use stdio transport (default):

# Set your API key and run the server (stdio transport for MCP clients)
$env:MATAROA_API_KEY="your-key"; python -m mataroa_mcp.server

The server communicates via stdio by default, which is the standard MCP transport.

For HTTP testing (advanced): To test with HTTP endpoints, modify the main() function in server.py to use:

mcp.run(transport="sse")  # or "streamable-http"

Then the server will listen on http://127.0.0.1:8000.

---

Troubleshooting

"Could not attach MCP server mataroa" in Claude Desktop

Causes:

• The mataroa-mcp command isn't on your PATH (Claude Desktop can't find the executable)
• MATAROA_API_KEY is missing or empty in the config's "env" block
• Port 8000 already in use from a previous server instance (only relevant if you're running with HTTP transport)

Solutions:

1. Confirm the install worked and the command is reachable: run mataroa-mcp (or uvx mataroa-mcp) directly in a terminal — it should print an error about the missing API key, not "command not found"
2. If mataroa-mcp isn't found, use uvx instead (it doesn't depend on your PATH), or provide the absolute path to the installed script (e.g. C:\Users\you\AppData\Local\Programs\Python\Python3xx\Scripts\mataroa-mcp.exe on Windows, or ~/.local/bin/mataroa-mcp on macOS/Linux)
3. Double-check MATAROA_API_KEY is set correctly in the config's "env" block
4. Make sure no other process is using port 8000: netstat -ano | findstr :8000
5. Restart Claude Desktop after making changes to claude_desktop_config.json

Tests fail with "async def functions are not natively supported"

This happens if pytest-asyncio isn't installed properly. Run:

pip install pytest-asyncio

Then restart your Python environment or terminal.

---

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ayush111111
• Source: ayush111111/matoroa-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.