🎯 MCP SERVER PESSOAL v1.0.0
Servidor MCP extensível para uso pessoal com Claude Desktop
🚀 Início Rápido (30 segundos)
Opção 1: Interface Web (Recomendado)
# Execute a interface web
start_web_interface.bat
# Abra no navegador
http://localhost:5000
Opção 2: Integração com Claude Desktop
# 1. Execute o menu interativo
run_tests.bat
# 2. Escolha [1] para testar
# 3. Escolha [2] para iniciar
# 4. Abra Claude Desktop e teste!
🎉 Pronto! Agora você pode usar comandos como:
"liste minhas tarefas""crie uma nota sobre Python""liste arquivos em C:\projetos"
📚 Documentação
- WEB_INTERFACE.md - Interface Web Completa 🌐 ⭐
- QUICKSTART_VISUAL.md - Guia visual rápido ⭐
- GUIA_TESTES.md - Como testar e verificar conexão
- COMO_USAR.md - Documentação completa
✨ Funcionalidades
🌐 Interface Web (NOVO!)
- Dashboard em tempo real com estatísticas
- Gerenciamento visual de tarefas
- Criação de tarefas com formulário intuitivo
- Logs do servidor ao vivo
- Atualização automática a cada 5 segundos
- Design moderno e responsivo
- Acesse:
start_web_interface.bat→ http://localhost:5000
📋 Gerenciamento de Tarefas
- Criar, listar, completar e deletar tarefas
- Buscar tarefas por texto
- Filtrar por status (pendente/concluída)
- Definir prioridades e datas limite
📝 Sistema de Notas
- Criar notas com tags
- Listar notas recentes
- Organização simples e eficiente
📁 Acesso a Arquivos
- Ler e escrever arquivos
- Listar diretórios
- Buscar arquivos
- Controle de permissões
📅 Calendário Google (Opcional)
- Criar eventos
- Listar próximos eventos
- Integração OAuth2
🛠️ Ferramentas Disponíveis
Menu Interativo (run_tests.bat)
╔══════════════════════════════════════════════════════════════════╗
║ MCP SERVER PESSOAL - MENU DE TESTE E EXECUÇÃO ║
╚══════════════════════════════════════════════════════════════════╝
[1] 🧪 Testar Servidor → Verifica funcionamento
[2] 🚀 Iniciar Servidor → Modo com feedback visual
[3] 📊 Monitor Real-time → Dashboard de atividade
[4] 📝 Ver Logs → Logs em tempo real
[5] 🔍 Ver Status → Status atual do servidor
[6] 🧹 Limpar Logs → Remove arquivos de log
[7] ❌ Sair
Scripts Individuais
| Script | Descrição |
|---|---|
test_connection.py | Executa bateria de testes completa |
main_verbose.py | Servidor com feedback detalhado |
monitor.py | Monitor visual em tempo real |
main.py | Servidor normal (produção) |
📊 Como Verificar se Está Funcionando
Método 1: Testes Automáticos (Recomendado)
run_tests.bat → [1] Testar Servidor
Resultado esperado:
✅ INITIALIZATION PASSOU
✅ MODULES PASSOU
✅ TASKS PASSOU
✅ FILESYSTEM PASSOU
✅ TOOLS PASSOU
🎉 TODOS OS TESTES PASSARAM!
Método 2: Monitor Visual
run_tests.bat → [3] Monitor em Tempo Real
Mostra:
- Status do servidor (rodando/parado)
- Estatísticas de logs
- Contador de tarefas
- Últimas linhas do log
Método 3: Teste no Claude Desktop
- Inicie o servidor:
run_tests.bat → [2] - Abra Claude Desktop
- Digite:
"liste minhas tarefas" - Se funcionar, está conectado! ✅
🔧 Configuração
Arquivo .env
# Debug
DEBUG=False
# Diretórios permitidos (separados por vírgula)
ALLOWED_DIRECTORIES="C:\projetos\IA,C:\Users\PC Gamer\Documents"
# Logs
LOG_LEVEL=INFO
LOG_FILE=./logs/mcp_server.log
# Tarefas
TASKS_DB_PATH=./data/tasks.json
# Google Calendar (opcional)
GOOGLE_CLIENT_ID=seu_client_id
GOOGLE_CLIENT_SECRET=seu_secret
Configuração no Claude Desktop
Arquivo: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"personal-server": {
"command": "C:\\projetos\\IA\\mcp\\mcp-tools2\\venv\\Scripts\\python.exe",
"args": ["C:\\projetos\\IA\\mcp\\mcp-tools2\\main.py"]
}
}
}
🐛 Solução de Problemas
❌ Servidor não inicia
# 1. Verifique dependências
venv\Scripts\activate
pip install -r requirements.txt
# 2. Teste com modo verbose
python main_verbose.py
# 3. Veja os logs
type logs\mcp_server.log
❌ Claude não reconhece os comandos
- Reinicie Claude Desktop completamente
- Verifique configuração:
%APPDATA%\Claude\claude_desktop_config.json - Monitore logs:
run_tests.bat → [4] - Execute testes:
run_tests.bat → [1]
❌ Testes falharam
# 1. Ative debug
echo DEBUG=True >> .env
# 2. Execute testes novamente
python test_connection.py
# 3. Veja erros detalhados nos logs
📦 Estrutura do Projeto
mcp-tools2/
├── 📄 README.md ⭐ Este arquivo
├── 📄 QUICKSTART_VISUAL.md 🚀 Guia visual rápido
├── 📄 GUIA_TESTES.md 🧪 Como testar
├── 📄 COMO_USAR.md 📚 Documentação completa
│
├── 🎮 run_tests.bat ⭐ Menu principal
├── 🧪 test_connection.py Testes automáticos
├── 📊 monitor.py Monitor visual
├── 🚀 main_verbose.py Servidor com feedback
├── ⚙️ main.py Servidor normal
│
├── core/ Núcleo do servidor
│ ├── server.py Servidor MCP principal
│ └── registry.py Registro de ferramentas
│
├── modules/ Módulos funcionais
│ ├── tasks/ Gerenciamento de tarefas
│ ├── filesystem/ Acesso a arquivos
│ └── calendar/ Integração com Google
│
├── config/ Configurações
│ ├── settings.py Configurações globais
│ └── logging.py Sistema de logs
│
├── logs/ Arquivos de log
│ └── mcp_server.log Log principal
│
└── data/ Dados persistentes
└── tasks.json Banco de tarefas
🎯 Casos de Uso
Desenvolvimento
# Terminal 1: Servidor com feedback
run_tests.bat → [2]
# Terminal 2: Monitor de atividade
run_tests.bat → [3]
# Trabalhar normalmente no Claude Desktop
Produção (dia a dia)
# Iniciar servidor
run_tests.bat → [2]
# Usar Claude Desktop normalmente
# O servidor roda em background
Debugging
# 1. Ativar debug
echo DEBUG=True > .env
# 2. Ver logs ao vivo
run_tests.bat → [4]
# 3. Usar Claude Desktop e ver o que acontece
📝 Comandos Exemplo no Claude
# Tarefas
"crie uma tarefa: Estudar Python"
"liste minhas tarefas pendentes"
"complete a tarefa 1"
"busque tarefas sobre Python"
"delete a tarefa 2"
# Notas
"crie uma nota sobre MCP Server"
"liste minhas últimas notas"
# Arquivos
"liste os arquivos em C:\projetos\IA"
"leia o arquivo README.md"
"crie um arquivo teste.txt com 'Hello World'"
"busque arquivos .py no diretório"
🔄 Atualizações
v1.0.0 (2025-10-18)
- ✅ Sistema de testes automáticos
- ✅ Menu interativo (run_tests.bat)
- ✅ Monitor visual em tempo real
- ✅ Modo verbose com feedback
- ✅ Documentação completa
- ✅ Melhor tratamento de erros
- ✅ Guias visuais (QUICKSTART_VISUAL.md, GUIA_TESTES.md)
🤝 Contribuindo
Este é um projeto pessoal, mas melhorias são bem-vindas!
- Faça fork do projeto
- Crie uma branch (
git checkout -b feature/nova-funcionalidade) - Commit suas mudanças (
git commit -am 'Adiciona nova funcionalidade') - Push para a branch (
git push origin feature/nova-funcionalidade) - Abra um Pull Request
📄 Licença
MIT License - use como quiser!
🆘 Precisa de Ajuda?
- Leia primeiro: QUICKSTART_VISUAL.md ⭐
- Testes: GUIA_TESTES.md
- Documentação: COMO_USAR.md
- Execute os testes:
run_tests.bat → [1] - Veja os logs:
run_tests.bat → [4]
🎉 Pronto para Começar?
run_tests.bat
É só isso! O menu vai te guiar. 🚀
Desenvolvido com ❤️ para integração com Claude Desktop
Última atualização: 18/10/2025