Expense Tracker MCP Server

Сервер 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: Math Addition 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\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json)

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

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

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

{
  "mcpServers": {
    "expense-server": {
      "command": "C:\\Users\\pyash\\AppData\\Local\\Python\\pythoncore-3.14-64\\Scripts\\uv.exe",
      "args": [
        "run",
        "--directory",
        "d:\\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