Band MCP Server

🚀 Band MCP Server

A fully functional Model Context Protocol (MCP) server integrating with the Band API, enabling seamless interaction with Band social platform data through AI assistants and other MCP-compatible tools.

🚀 Quick Start

Prerequisites

• Band API access token (obtainable from Band Developer Portal)
• VS Code with MCP support or any MCP-compatible client
• Docker (for containerized deployment)

VS Code Integration

Add the following configuration to your VS Code settings.json:

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "band_access_token",
        "description": "BAND Access Token",
        "password": true
      }
    ],
    "servers": {
      "band-mcp-server": {
        "command": "docker",
        "args": ["run", "--rm", "-i", "-e", "BAND_ACCESS_TOKEN", "kanghouchao/band-mcp-server:latest"],
        "env": {
          "BAND_ACCESS_TOKEN": "${input:band_access_token}"
        }
      }
    }
  }
}

Local Development

# Clone the repository
git clone <repository-url>
cd band-mcp-server

# Install dependencies
make install
# or
npm install

# Set up environment variables
echo "BAND_ACCESS_TOKEN=your_token_here" > .env

# Run in development mode
make dev
# or
npm run dev

# Build the project
make build
# or
npm run build

# Run tests
make test
# or
npm test

Docker Deployment

# Build Docker image
make docker-build
# or
docker build -t band-mcp-server:latest .

# Run Docker container
make docker-run
# or
docker run --rm -i -e BAND_ACCESS_TOKEN=your_token_here band-mcp-server:latest

✨ Features

• Access Token Authentication: Securely authenticate using Band API access tokens.
• Complete Band API Coverage: Full implementation of all major Band API endpoints.
• Read/Write Operations: Comprehensive CRUD operations for posts, comments, and band data.
• MCP Integration: Native MCP tools and resources for seamless AI integration.
• Docker Deployment: Production-ready containerized deployment.
• TypeScript Implementation: Type-safe implementation with full error handling.
• Automated CI/CD: Continuous integration and automated Docker builds.

📦 Installation

This MCP server is fully implemented and provides complete access to Band API functionality including user profiles, band management, posts, comments, albums, and photos with full read/write capabilities.

Version: 1.0.3
Docker Image: kanghouchao/band-mcp-server:latest

💻 Usage Examples

// Get all bands the user belongs to
await mcp.callTool("get_bands", {});

// Get recent posts from a specific band
await mcp.callTool("get_posts", {
  band_key: "AADoj33YIR6g5reUiHGZx0wj",
  limit: 20
});

// Create a new post
await mcp.callTool("write_post", {
  band_key: "AADoj33YIR6g5reUiHGZx0wj",
  content: "Hello from MCP! 🚀",
  do_push: false
});

// Add a comment to a post
await mcp.callTool("write_comment", {
  band_key: "AADoj33YIR6g5reUiHGZx0wj",
  post_key: "AAB8tbywKWMoGQFLqd_EhiBD",
  body: "Great post! 👍"
});

📚 Documentation

Available MCP Tools

User & Band Management

• get_user_information - Get user profile information for a Band group
• get_bands - Get list of all Band groups the authenticated user belongs to
• permissions - Check user permissions for a specific Band (posting, commenting, deletion rights)

Posts & Content

• get_posts - Get posts from a specific Band with pagination support
• get_post - Get detailed information about a specific post
• write_post - Create a new post in a Band group
• remove_post - Delete a post from a Band (requires appropriate permissions)

Comments & Interactions

• get_comments - Get comments for a specific post with sorting options
• write_comment - Add a comment to a post
• remove_comment - Delete a comment from a post (requires appropriate permissions)

Media & Albums

• get_albums - Get photo albums in a Band group
• get_photos - Get photos from a specific album

Troubleshooting

Common Issues

• "Authentication failed":
  • Verify your Band API access token is valid and not expired.
  • Ensure the token has the necessary permissions for the operations you're trying to perform.
  • Check that the token is correctly set in the environment variable BAND_ACCESS_TOKEN.
• "Permission denied" errors:
  • Some operations require specific roles within a Band (leader, co - leader, etc.).
  • Use the permissions tool to check your access rights for a specific Band.
  • Contact the Band administrator to request appropriate permissions.
• Docker container issues:
  • Ensure Docker is running and you have sufficient permissions.
  • Check that the environment variable is properly passed to the container.
  • Verify the Docker image is up to date: docker pull kanghouchao/band-mcp-server:latest.
• MCP client connection issues:
  • Verify your MCP client supports the required protocol version.
  • Check that the server command and arguments are correctly configured.
  • Review VS Code or client logs for detailed error messages.

Debug Mode

To enable detailed logging, set the environment variable:

export DEBUG=band-mcp-server:*

Contributing

We welcome contributions! Please follow these guidelines:

1. Fork the repository and create a feature branch.
2. Write tests for new functionality.
3. Follow TypeScript best practices and maintain type safety.
4. Update documentation for any API changes.
5. Run tests and linting before submitting:

   npm run test
   npm run lint
   

6. Submit a pull request with a clear description of changes.

🔧 Technical Details

Project Structure

src/
├── index.ts          # Main MCP server entry point
├── tools.ts          # Tool definitions and routing
├── client.ts         # Band API client
├── config.ts         # Configuration management
└── [feature]/        # Individual tool implementations
    ├── index.ts      # Tool definition
    └── tool.ts       # Tool implementation

Available Scripts

• npm run dev - Development mode with hot reload
• npm run build - Build TypeScript to JavaScript
• npm run test - Run test suite
• npm run lint - Run ESLint
• make help - Show all available Makefile commands

Error Handling & API Limits

The server implements comprehensive error handling and respects Band API rate limits:

• Authentication errors: Clear error messages for invalid or expired tokens.
• Permission errors: Detailed feedback when operations require higher permissions.
• Rate limiting: Automatic handling of API rate limits with appropriate delays.
• Validation: Input validation for all parameters using Zod schemas.
• Logging: Comprehensive logging for debugging and monitoring.

Performance Optimization

Current focus is on optimizing API response data to improve AI processing speed by:

• Filtering unnecessary data fields.
• Implementing selective field queries.
• Reducing payload sizes for better performance.

Security Considerations

• Token Security: Never commit access tokens to version control.
• Environment Variables: Always use environment variables for sensitive data.
• Permissions: Follow principle of least privilege when requesting API permissions.
• Rate Limiting: Respect Band API rate limits to avoid service disruption.
• Input Validation: All inputs are validated using Zod schemas.

📄 License

MIT License - see LICENSE file for details.

Maintainer: kanghouchao
Docker Hub: kanghouchao/band-mcp-server
Issues: Please report bugs and feature requests via GitHub Issues