ybro2011/xiaozhi-uk-mcp-server

Xiaozhi UK MCP Server

Custom MCP (Model Context Protocol) tools for XIAO ESP32S3 Sense, tailored for British users.

🚀 Quick Start

Prerequisites

• Docker Desktop installed and running
• XIAO ESP32S3 Sense device connected to Xiaozhi server

Start the Services

cd xiaozhi-uk-mcp-server
docker-compose up -d

Access MCPHub Dashboard

1. Open browser: http://localhost:3000
2. Login: admin / ChangeThisPassword456!
3. Add your device endpoint in the Xiaozhi section
4. Enable the Xiaozhi client service

🌐 Deploy Online

Ready to deploy your MCP Hub server online? We've made it easy!

Quick Deployment Options

1. Render.com (Recommended - Easiest)

   • Free tier available
   • Connect GitHub, auto-deploy
   • See for step-by-step instructions

2. Railway

   • $5 free credits/month
   • Great GitHub integration
   • See for instructions

3. Oracle Cloud (Free Forever)

   • Best free option with most resources
   • See for complete setup

Quick Start for Deployment

# Run the deployment preparation script
./deploy-quick.sh

# Then follow the platform-specific guide
# See DEPLOY.md for Render/Railway
# See HOSTING_GUIDE.md for Oracle Cloud/VPS

Full deployment guide: See for detailed instructions on all platforms.

📦 What's Included

1. UK Transport & News Server (5 tools)

Real-time UK public transport information:

• 🚇 London Underground status
• 🚂 National Rail live departures
• 🚌 Bus arrivals (with stop ID)
• 🚉 Station search
• 📰 BBC & Guardian news

Voice Commands:

• "What's the tube status?"
• "Next train from King's Cross"
• "Latest BBC news"

2. TTS Book Reader Server (6 tools)

Access to 70,000+ free audiobooks:

• 📚 Search books by title/author/subject
• 📖 Browse popular & recent books
• 🔖 Automatic bookmarking
• ⏯️ Resume reading anytime
• 📊 Progress tracking

Voice Commands:

• "Find books about mystery"
• "Start reading Pride and Prejudice"
• "Continue reading"

3. Built-in Servers

• Fetch (web content)
• Amap (maps - China-focused)
• Playwright (browser automation - optional)
• Slack (messaging - optional)

🛠️ Services

📖 Documentation

• - Complete development history, fixes, and learning (MAIN DOC)
• - LibriVox upload instructions (ready to upload)

🎯 Current Status

✅ MCPHub Running - Docker containers active
✅ UK Transport MCP - 5 tools connected
✅ Book Reader MCP - 6 tools connected
✅ Device Connected - XIAO device linked to mcphub
✅ 24 Total Tools - Available to your device

🔑 API Keys Required

Currently using free APIs only:

• ✅ Transport for London (TfL) - No key needed
• ✅ Huxley2 (National Rail) - No key needed
• ✅ BBC/Guardian RSS - No key needed
• ✅ Project Gutenberg - No key needed

No API keys or subscriptions required! 🎉

📝 Common Commands

# Start services
docker-compose up -d

# Stop services
docker-compose down

# Restart MCPHub
docker restart xiaozhi-mcphub

# View logs
docker logs -f xiaozhi-mcphub

# Access database
docker exec -it xiaozhi-postgres psql -U xiaozhi -d xiaozhi_mcphub

🧪 Testing

Test UK Transport:

Ask your device:

• "What's the status of the London Underground?"
• "When's the next train from Paddington?"
• "Latest UK news"

Test Book Reader:

Ask your device:

• "Find books about Sherlock Holmes"
• "Start reading book 1661"
• "Continue reading"

📁 Project Structure

xiaozhi-uk-mcp-server/
├── docker-compose.yml              # Docker services
├── .env                            # Environment variables (gitignored)
├── .gitignore                      # Git ignore rules
├── README.md                       # This file
├── DEVELOPMENT_GUIDE.md            # Complete development guide
├── BOOK_READER_GUIDE.md            # Book reader user guide
├── FIXES_SUMMARY.md                # Troubleshooting history
│
├── uk-transport-server/            # UK transport MCP
│   ├── package.json
│   ├── index.js
│   └── wrapper.sh
│
├── book-reader-server/             # Book reader MCP
│   ├── package.json
│   ├── index.js
│   └── wrapper.sh
│
└── patches/                        # Fixes for mcphub
    ├── simple_patch.js             # JSON parsing fix
    ├── fix_package_json.js         # Module type fix
    └── *.sql                       # Database configurations

🎓 Accessibility Features

Perfect for:

• ✅ Elderly users - Voice-only interface, no screens needed
• ✅ Visually impaired - Audio-first design
• ✅ UK residents - Localized transport info
• ✅ Book lovers - 70,000+ free audiobooks

🔧 Troubleshooting

If tools aren't working:

1. Check Docker is running: docker ps
2. Check mcphub logs: docker logs xiaozhi-mcphub
3. Verify database: See DEVELOPMENT_GUIDE.md section 5
4. Check Xiaozhi service: Must be enabled in mcphub dashboard
5. Verify endpoint: Device MCP endpoint must be added and connected

🌟 What Makes This Special

✨ No subscriptions - All APIs are free
✨ UK-focused - TfL, National Rail, BBC, Guardian
✨ Accessible - Designed for elderly & visually impaired
✨ Offline-capable - Bookmarks work without internet
✨ Privacy-first - Self-hosted, your data stays with you
✨ Expandable - Easy to add more tools

📚 Resources

• Xiaozhi Official Docs: https://x0ntkzs0zde.feishu.cn/docx/JKFXd8bLYo6YZtxz9ORcbnA8nbe
• Project Gutenberg: https://www.gutenberg.org
• Gutendex API: https://gutendex.com
• TfL API: https://api.tfl.gov.uk
• National Rail Codes: https://www.nationalrail.co.uk/stations/

🎉 Success!

You now have a fully functional, UK-focused AI assistant with:

• Real-time transport information
• Latest UK news
• 70,000+ audiobooks
• All running locally and privately!

Enjoy your enhanced XIAO device! 🎊

Created: 2025-10-16
Author: Xiaozhi UK User
License: MIT