Сервер MCP для учёта расходов

Сервер Model Context Protocol (MCP), созданный на базе FastMCP (v3.x) и Python, предназначен для предоставления инструментов и ресурсов для учёта расходов MCP-совместимым клиентам, таким как Claude Desktop и MCP Inspector.

📋 Предварительные требования

• Python: 3.10+ (проверено на Python 3.14)

• uv: Быстрый установщик пакетов и резолвер Python (astral.sh/uv)

• Node.js: v22.x или v24.x (LTS) — требуется для интерфейса MCP Inspector

• Claude Desktop (необязательно): для тестирования инструментов прямо в Claude

Related MCP server: Demo MCP Server

🚀 Установка и настройка

1. Инициализация проекта и окружения

# Initialize uv project (if starting fresh)
uv init .

# Install FastMCP
uv add fastmcp

2. Подготовка Node.js для интерфейса MCP Inspector

MCP Inspector (@modelcontextprotocol/inspector) требует Node.js v22.19.0+ или v24+. Если используется nvm-windows:

nvm install lts
nvm use 24

Установите inspector глобально или разрешите npx загрузить его:

npm install -g @modelcontextprotocol/inspector

🛠️ Запуск и разработка

Вариант A: Интерактивный веб-интерфейс (MCP Inspector)

Чтобы запустить веб-интерфейс MCP Inspector с горячей перезагрузкой:

uv run fastmcp dev inspector main.py

• Оставьте это окно терминала открытым.

• Консоль выведет локальный URL с токеном аутентификации:

  MCP Inspector Web is up and running at:
     http://127.0.0.1:6274?MCP_INSPECTOR_API_TOKEN=<token>

• Откройте эту ссылку в браузере, чтобы тестировать инструменты, просматривать схемы и видеть логи запросов и ответов в реальном времени.

Вариант B: Прямой запуск сервера (STDIO)

Чтобы запустить MCP-сервер в режиме стандартного ввода-вывода:

uv run fastmcp run main.py

(или uv run python main.py)

🤖 Подключение к Claude Desktop

1. Расположение файла конфигурации

В Windows конфигурация Claude Desktop хранится по адресу:

%APPDATA%\Claude\claude_desktop_config.json

(Полный путь: C:\Users\<ВашеИмяПользователя>\AppData\Roaming\Claude\claude_desktop_config.json)

2. Настройки конфигурации

Добавьте определение expense-server в раздел mcpServers.

Примечание: В Windows GUI-приложения, такие как Claude Desktop, часто не наследуют PATH из оболочки. Всегда указывайте абсолютный путь к файлу uv.exe.

{
  "mcpServers": {
    "expense-server": {
      "command": "C:\\Users\\hp\\AppData\\Local\\Python\\pythoncore-3.14-64\\Scripts\\uv.exe",
      "args": [
        "run",
        "--directory",
        "g:\\Projects\\expense-tracker-mcp-server",
        "fastmcp",
        "run",
        "main.py"
      ]
    }
  }
}

3. Перезапуск Claude Desktop

1. Полностью закройте Claude Desktop (убедитесь, что приложение закрыто из системного трея Windows рядом с часами).

2. Снова откройте Claude Desktop.

3. Проверьте Settings > Developer, чтобы убедиться, что expense-server подключён.

🧰 Доступные инструменты (текущий main.py)

🔧 Устранение неполадок

1. Unknown command "main.py". Available commands: inspector, apps.

В FastMCP 3.x fastmcp dev — это группа команд. Используйте fastmcp dev inspector main.py вместо fastmcp dev main.py.

2. node:util does not provide an export named 'styleText'

Версия Node.js старше v20.12. Обновитесь до Node v22+ или v24+ с помощью nvm install lts && nvm use 24.

3. Cannot find native binding (npm optional dependencies bug)

Повреждённый кэш npx из-за переключения версий Node. Выполните:

npm cache clean --force
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx" -ErrorAction SilentlyContinue
npm install -g @modelcontextprotocol/inspector