{
  "markdown": "# Hibiki MCP Server\n\n[![npm version](https://badge.fury.io/js/@hibiki%2Fmcp-server.svg)](https://www.npmjs.com/package/@hibiki/mcp-server)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.zeiq--co%2Fhibiki--mcp-blue)](https://registry.modelcontextprotocol.io/servers/io.github.gethibiki/mcp)\n[![Smithery](https://img.shields.io/badge/Smithery-Deploy-green)](https://smithery.ai/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![smithery badge](https://smithery.ai/badge/@gethibiki/mcp)](https://smithery.ai/server/@gethibiki/mcp)\n\nModel Context Protocol (MCP) server for [Hibiki](https://gethibiki.com) content creation platform. This server enables AI assistants and tools to create and retrieve content through Hibiki's API.\n\n**✨ NEW:** [Claude Code Plugin](#claude-code-plugin) now available with slash commands and specialized AI agents for streamlined content creation workflows!\n\n## Quick Start\n\n```bash\n# Install via npx\nnpx @hibiki/mcp-server --api-key YOUR_API_KEY\n\n# Or configure in Claude Desktop (see Configuration below)\n```\n\nGet your API key at [www.gethibiki.com/settings/api-keys](https://www.gethibiki.com/settings/api-keys)\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [Features](#features)\n- [Claude Code Plugin](#claude-code-plugin)\n- [Installation](#installation)\n- [Usage](#usage)\n- [MCP Client Configuration](#mcp-client-configuration)\n- [Available Tools](#available-tools)\n- [Available Resources](#available-resources)\n- [Development](#development)\n- [API Integration](#api-integration)\n- [Examples](#examples)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [Support](#support)\n- [Changelog](#changelog)\n\n## Features\n\n- **Create Content**: Generate platform-optimized content with AI enhancement\n- **Retrieve & Manage Posts**: Fetch, list, and update post data with pagination\n- **Multi-Platform Support**: Twitter, Instagram, LinkedIn, Facebook, Threads, Blog, Reddit\n- **Brand Styles**: Apply consistent voice, tone, and visual styling with brand presets\n- **Image Generation**: Optionally generate images for your content\n- **Scheduling**: Schedule posts for future publication\n- **Dual Transport**: Supports both stdio (local) and HTTP transports (Smithery/cloud deployment)\n- **Type-Safe**: Built with TypeScript and Zod validation\n\n## Claude Code Plugin\n\n**NEW!** We've created an official Claude Code plugin that makes social media content creation even easier with user-friendly commands and specialized AI agents.\n\n### What is it?\n\nThe Hibiki plugin for Claude Code provides:\n\n- **5 Slash Commands**: Quick access to common workflows\n  - `/create-content` - Create multi-platform posts with AI guidance\n  - `/schedule-post` - Schedule posts for optimal engagement times\n  - `/view-brands` - Browse and manage your brand styles\n  - `/manage-posts` - List, filter, and manage all your posts\n  - `/preview-post` - Preview platform-specific content formatting\n\n- **3 Specialized Agents**: Expert AI assistants for specific tasks\n  - **Content Creator** - Expert at crafting engaging, platform-optimized content\n  - **Brand Manager** - Ensures brand consistency across all platforms\n  - **Social Media Optimizer** - Maximizes reach and engagement through data-driven strategies\n\n### Quick Start with Plugin\n\n```bash\n# Install the plugin\nclaude plugin install hibiki\n\n# Set your API key\nexport HIBIKI_API_KEY=\"your-api-key-here\"\n\n# Start creating content\nclaude /create-content \"Announcing our new feature\"\n\n# Or use an agent\nclaude \"Content Creator, help me announce our product launch\"\n```\n\n### Documentation\n\nFull plugin documentation, installation instructions, and usage examples are available in the [claude-code-plugin](./claude-code-plugin) directory.\n\nSee [claude-code-plugin/README.md](./claude-code-plugin/README.md) for:\n\n- Detailed installation instructions\n- Complete command reference\n- Agent usage guides\n- Advanced workflows and examples\n- Troubleshooting tips\n\n## Installation\n\n### Via MCP Registry (Recommended)\n\nThe server is published in the [official MCP Registry](https://registry.modelcontextprotocol.io/) as `io.github.gethibiki/mcp`.\n\nBrowse and install via the registry web interface, or configure directly in your MCP client (see [MCP Client Configuration](#mcp-client-configuration) below).\n\n### Via Smithery (Zero-Setup Deployment)\n\nThe easiest way to get started is through [Smithery](https://smithery.ai/), which provides:\n\n- **One-click installation** - No local dependencies or configuration needed\n- **Automatic updates** - Always get the latest version\n- **Secure hosting** - Your API keys are safely managed\n- **Interactive playground** - Test tools before using them\n\nInstall from Smithery:\n\n1. Visit the [Hibiki MCP Server on Smithery](https://smithery.ai/server/@gethibiki/mcp)\n2. Click \"Install\"\n3. Enter your Hibiki API key when prompted\n4. Start using immediately in Claude Desktop or other MCP clients\n\n### Global Installation (via npx)\n\n```bash\nnpx @hibiki/mcp-server --api-key YOUR_API_KEY\n```\n\n### Local Development\n\n```bash\ngit clone https://github.com/gethibiki/mcp.git\ncd hibiki-mcp\npnpm install\npnpm build\n```\n\n## Usage\n\n### Prerequisites\n\nYou'll need a Hibiki API key. Generate one at:\n\n- Production: <https://www.gethibiki.com/settings/api-keys>\n- Development: <http://localhost:3000/settings/api-keys>\n\n### Running the Server\n\n#### Stdio Mode (Local)\n\nThis is the default mode for use with MCP clients like Claude Desktop:\n\n```bash\nnpx @hibiki/mcp-server --api-key YOUR_API_KEY\n```\n\nOr debug with MCP Inspector:\n\n```bash\nnpx @modelcontextprotocol/inspector npx @hibiki/mcp-server --api-key YOUR_API_KEY\n```\n\nWith custom base URL:\n\n```bash\nnpx @hibiki/mcp-server \\\n  --api-key YOUR_API_KEY \\\n  --base-url https://www.gethibiki.com\n```\n\n#### Remote HTTP Server Mode\n\nRun the server in HTTP mode for cloud deployments (like Smithery) or to expose the server over HTTP:\n\n```bash\nnpx @hibiki/mcp-server --remote --api-key YOUR_API_KEY\n```\n\nThe server will start an HTTP server on port 8081 (configurable via `PORT` environment variable) with:\n\n- `/mcp` - Main MCP endpoint (POST)\n- `/health` - Health check endpoint (GET)\n\nWith custom configuration:\n\n```bash\nPORT=3000 npx @hibiki/mcp-server \\\n  --remote \\\n  --api-key YOUR_API_KEY \\\n  --base-url https://www.gethibiki.com\n```\n\n**Note:** In HTTP mode, the server implements [MCP Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) with proper CORS configuration for browser-based clients.\n\n### Environment Variables\n\nInstead of command-line flags, you can use environment variables:\n\n**For stdio mode:**\n\n```bash\nexport HIBIKI_API_KEY=your_api_key\nexport HIBIKI_BASE_URL=http://localhost:3000\nnpx @hibiki/mcp-server\n```\n\n**For HTTP mode:**\n\n```bash\nexport HIBIKI_API_KEY=your_api_key\nexport HIBIKI_BASE_URL=https://www.gethibiki.com\nexport PORT=8081\nnpx @hibiki/mcp-server --remote\n```\n\nAvailable environment variables:\n\n- `HIBIKI_API_KEY` - Your Hibiki API key (stdio mode only; HTTP mode uses query params)\n- `HIBIKI_BASE_URL` - Base URL for Hibiki API (default: `https://www.gethibiki.com`)\n- `PORT` - HTTP server port (HTTP mode only, default: `8081`)\n\n## MCP Client Configuration\n\n### Claude Desktop\n\nAdd to your Claude Desktop config file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"hibiki\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"@hibiki/mcp-server\",\n        \"--api-key\",\n        \"YOUR_API_KEY\",\n        \"--base-url\",\n        \"http://localhost:3000\"\n      ]\n    }\n  }\n}\n```\n\n### Other MCP Clients\n\nFor other MCP clients that support stdio transport, use a similar configuration with appropriate command and args.\n\n## Available Tools\n\nThe server provides 6 tools for managing Hibiki content:\n\n| Tool | Description |\n|------|-------------|\n| `create-post` | Create multi-platform content with AI enhancement |\n| `get-post` | Retrieve a specific post by ID |\n| `get-all-posts` | List posts with pagination and filtering |\n| `update-post` | Update existing post title, content, or status |\n| `get-brand-styles` | List all available brand styles |\n| `get-brand-style` | Get detailed brand style configuration |\n\n### create-post\n\nCreate a new content post with platform-specific variations.\n\n**Parameters:**\n\n- `content` (required): The original content to be enhanced\n- `platforms` (required): Array of target platforms\n  - Options: `twitter`, `instagram`, `linkedin`, `facebook`, `threads`, `blog`, `reddit`\n- `length` (optional): Content length - `very-short`, `short`, `medium`, `long` (default: `medium`)\n- `createImage` (optional): Generate an image (default: `false`)\n- `createHashtags` (optional): Generate hashtags (default: `true`)\n- `scheduleTime` (optional): ISO 8601 datetime to schedule the post\n- `postToSocialNetworks` (optional): Immediately post to connected networks (default: `false`)\n- `brandStyleId` (optional): Brand style UUID to apply\n\n**Example:**\n\n```json\n{\n  \"content\": \"Just launched our new AI-powered content creation tool!\",\n  \"platforms\": [\"twitter\", \"linkedin\"],\n  \"length\": \"medium\",\n  \"createImage\": true,\n  \"createHashtags\": true\n}\n```\n\n**Returns:**\n\n- Post ID\n- Original content\n- Platform-specific enhanced content\n- Generated images (if requested)\n- Hashtags for each platform\n- Status and timestamps\n\n### get-post\n\nRetrieve a post by its ID.\n\n**Parameters:**\n\n- `postId` (required): UUID of the post\n\n**Example:**\n\n```json\n{\n  \"postId\": \"123e4567-e89b-12d3-a456-426614174000\"\n}\n```\n\n**Returns:**\n\n- Complete post data\n- Platform-specific content\n- Generated images\n- Status and metadata\n\n### get-all-posts\n\nList all posts with pagination and filtering.\n\n**Parameters:**\n\n- `page` (optional): Page number (default: `1`)\n- `limit` (optional): Posts per page (default: `10`)\n- `status` (optional): Filter by status - `draft`, `scheduled`, `published`\n\n**Example:**\n\n```json\n{\n  \"page\": 1,\n  \"limit\": 20,\n  \"status\": \"published\"\n}\n```\n\n**Returns:**\n\n- Array of posts with metadata\n- Pagination information\n- Total count\n\n### update-post\n\nUpdate an existing post.\n\n**Parameters:**\n\n- `postId` (required): UUID of the post to update\n- `title` (optional): New title for the post\n- `content` (optional): New content\n- `status` (optional): New status - `draft`, `scheduled`, `published`\n\n**Example:**\n\n```json\n{\n  \"postId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"title\": \"Updated Title\",\n  \"status\": \"published\"\n}\n```\n\n**Returns:**\n\n- Updated post data\n- Confirmation message\n\n### get-brand-styles\n\nList all available brand styles for your account.\n\n**Parameters:** None\n\n**Returns:**\n\n- Array of brand styles with IDs and names\n- Style metadata\n\n### get-brand-style\n\nGet details for a specific brand style.\n\n**Parameters:**\n\n- `brandStyleId` (required): UUID of the brand style\n\n**Example:**\n\n```json\n{\n  \"brandStyleId\": \"123e4567-e89b-12d3-a456-426614174000\"\n}\n```\n\n**Returns:**\n\n- Brand style name and description\n- Color palette\n- Typography settings\n- Tone and voice guidelines\n- Imagery preferences\n\n## Available Resources\n\n### post://{postId}\n\nAccess post data as an MCP resource.\n\n**Example URI:**\n\n```\npost://123e4567-e89b-12d3-a456-426614174000\n```\n\n### preview://{postId}/{platform}\n\nGet platform-specific preview content.\n\n**Example URI:**\n\n```\npreview://123e4567-e89b-12d3-a456-426614174000/twitter\n```\n\n## Development\n\n### Building\n\n```bash\npnpm build\n```\n\n### Running Locally\n\n```bash\npnpm start -- --api-key YOUR_API_KEY\n```\n\n### Type Checking\n\n```bash\npnpm typecheck\n```\n\n### Development Mode (Watch)\n\n```bash\npnpm dev\n```\n\n## API Integration\n\nThe MCP server connects to Hibiki's REST API endpoints:\n\n- `POST /api/v1/posts` - Create new posts\n- `GET /api/v1/posts/{postId}` - Retrieve single post\n- `GET /api/v1/posts` - List posts with pagination\n- `PUT /api/v1/posts/{postId}` - Update existing post\n- `GET /api/v1/brand-styles` - List brand styles\n- `GET /api/v1/brand-styles/{brandStyleId}` - Get brand style details\n\nAll requests require the `X-API-Key` header for authentication.\n\n## Error Handling\n\nThe server provides detailed error messages for common issues:\n\n- **Invalid API Key**: Check your API key is correct and active\n- **Rate Limit Exceeded**: Wait before making additional requests\n- **Post Not Found**: Verify the post ID is correct\n- **Invalid Parameters**: Check parameter types and formats\n- **Network Errors**: Verify the base URL and network connection\n\n## Examples\n\n### Creating a Multi-Platform Post\n\n```typescript\n// Using the create-post tool\n{\n  \"content\": \"Excited to share our latest feature! \\ud83d\\ude80 AI-powered content optimization for all your social platforms.\",\n  \"platforms\": [\"twitter\", \"linkedin\", \"instagram\"],\n  \"length\": \"medium\",\n  \"createImage\": true,\n  \"createHashtags\": true\n}\n```\n\n### Scheduling a Post\n\n```typescript\n{\n  \"content\": \"Join us for our product launch next week!\",\n  \"platforms\": [\"twitter\", \"linkedin\"],\n  \"scheduleTime\": \"2025-10-20T14:00:00Z\",\n  \"createImage\": true\n}\n```\n\n### Retrieving Post Data\n\n```typescript\n// Using the get-post tool\n{\n  \"postId\": \"123e4567-e89b-12d3-a456-426614174000\"\n}\n```\n\n### Accessing Resources\n\n```typescript\n// Read post resource\n{\n  \"uri\": \"post://123e4567-e89b-12d3-a456-426614174000\"\n}\n\n// Read platform-specific preview\n{\n  \"uri\": \"preview://123e4567-e89b-12d3-a456-426614174000/twitter\"\n}\n```\n\n### Testing HTTP Mode Locally\n\nStart the server in HTTP mode:\n\n```bash\nnpx @hibiki/mcp-server --remote --api-key YOUR_API_KEY\n```\n\nTest the health endpoint:\n\n```bash\ncurl http://localhost:8081/health\n```\n\nTest the MCP endpoint with MCP Inspector:\n\n```bash\nnpx @modelcontextprotocol/inspector http://localhost:8081/mcp?apiKey=YOUR_API_KEY\n```\n\nOr use with a Streamable HTTP MCP client that supports query-based configuration.\n\n## Troubleshooting\n\n### Server won't start\n\n- Check that you have Node.js 18+ installed\n- Verify your API key is valid\n- Ensure the base URL is correct and accessible\n\n### Tool calls fail\n\n- Verify your API key has the required permissions\n- Check rate limits haven't been exceeded\n- Ensure post IDs are valid UUIDs\n- Verify platform names are spelled correctly\n\n### HTTP mode not accessible\n\n- Check the port isn't already in use: `lsof -i :8081` (or your configured PORT)\n- Verify firewall settings allow the connection\n- Ensure the server process is running with the `--remote` flag\n- Check the server logs for any startup errors\n- Verify the `/health` endpoint responds: `curl http://localhost:8081/health`\n- For Smithery deployments, check the deployment logs in the Smithery dashboard\n\n### Smithery deployment fails\n\n- Ensure your GitHub repository is public or connected to Smithery\n- Verify `smithery.yaml` and `Dockerfile` are in the repository root\n- Check the build logs in Smithery dashboard for specific errors\n- Ensure all dependencies are declared in `package.json`\n- Try building the Docker image locally: `docker build -t hibiki-mcp .`\n\n## Contributing\n\nContributions are welcome! Please follow these steps:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nPlease ensure your code:\n\n- Follows the existing TypeScript style\n- Includes appropriate Zod schemas for validation\n- Updates documentation as needed\n- Passes type checking (`pnpm typecheck`)\n- Uses `console.error()` for logging (not `console.log()` - it breaks stdio mode)\n\n### For Maintainers\n\nSee [PUBLISHING.md](PUBLISHING.md) for detailed instructions on building and publishing updates.\n\n## Support\n\n- **Smithery**: <https://smithery.ai/> (One-click deployment)\n- **MCP Registry**: <https://registry.modelcontextprotocol.io/servers/io.github.gethibiki/mcp>\n- **npm Package**: <https://www.npmjs.com/package/@hibiki/mcp-server>\n- **Documentation**: <https://docs.gethibiki.com>\n- **Issues**: <https://github.com/gethibiki/mcp/issues>\n- **API Reference**: <https://docs.gethibiki.com/api>\n\n## License\n\nMIT License - see the [LICENSE](LICENSE) file for details.\n\n## Changelog\n\n### v1.3.0 (2025-10-10)\n\n- **NEW**: Added official Claude Code plugin\n- **NEW**: 5 slash commands for streamlined content workflows\n- **NEW**: 3 specialized AI agents (Content Creator, Brand Manager, Social Media Optimizer)\n- Plugin provides user-friendly interface to all MCP server capabilities\n- Comprehensive plugin documentation and usage examples\n- Enhanced developer experience for Claude Code users\n\n### v1.2.0 (2025-10-08)\n\n- **NEW**: Added HTTP transport support for Smithery and cloud deployments\n- **NEW**: Implemented MCP Streamable HTTP with `/mcp` and `/health` endpoints\n- Server now supports dual transport modes: stdio (local) and HTTP (remote)\n- Added Express and CORS dependencies for HTTP server\n- Added Dockerfile for containerized deployment\n- Configured for Smithery deployment with proper HTTP runtime\n- HTTP mode supports configuration via query parameters\n- Maintains backward compatibility with stdio mode for Claude Desktop\n\n### v1.0.3 (2025-10-08)\n\n- Added comprehensive publishing documentation (PUBLISHING.md)\n- Removed all debug console logs from config\n- Improved contributor guidelines\n\n### v1.0.2 (2025-10-08)\n\n- **CRITICAL FIX**: Removed console.log statements breaking stdio JSON-RPC protocol\n- Changed debug output to stderr to prevent JSON parsing errors\n- Server now works correctly with Claude Desktop and other MCP clients\n\n### v1.0.1 (2025-10-08)\n\n- Published to official MCP Registry\n- Updated package metadata\n- Complete tool documentation\n\n### v1.0.0 (2025-10-08)\n\n- Initial release\n- Support for 6 Hibiki API tools\n- Multi-platform content creation\n- Brand style integration\n",
  "bytes": 17905,
  "sha": "0a0ed0ffb4246db7901309d0b9fbbd243fb1dc2333fd70595af6db91f93673bf",
  "repo_slug": "perminder-klair/thoth-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_zeiq_co_thoth_mcp_246f208d/readme"
}