Dana MCP Server

What is Dana MCP Server about?

Dana MCP Server is a cross‑platform Python service that extends AI chatbots (e.g., ChatGPT, Claude, Grok) with real‑world execution capabilities. By exposing a tokenized MCP endpoint, it lets the model invoke tools on the underlying machine—reading/writing files, running builds, inspecting code, handling Git, orchestrating containers, querying databases, automating browsers, extracting PDFs, generating documents, and performing advanced engineering analysis.

How to use Dana MCP Server?

1. Install the package (recommended via Dana Desktop or CLI):

   git clone https://github.com/seyed-ali-002/Dana-MCP-Server.git
   cd Dana-MCP-Server
   python3 -m pip install -e .
   

2. Start the runtime with the provided CLI:

   dana run            # launches the MCP listener
   # other helpers
   dana start
   dana stop
   dana status
   

3. Configure networking:
   • For local use, connect to http://127.0.0.1:8765/<TOKEN>/mcp.
   • For remote access, enable Tailscale Funnel and use the public URL https://<machine>.<tailnet>.ts.net/<TOKEN>/mcp.
4. Connect an AI client by supplying the tokenized URL in the client’s MCP connector configuration.
5. Secure access via config/access_policy.json and rotate tokens with python scripts/regenerate_token.py when needed.

Key Features of Dana MCP Server

• Progressive Tool Discovery – only a minimal core set is sent to the client; the full registry is discovered on demand.
• Concurrent Workers – multiple AI sessions share a pool of worker slots, enabling parallel tool execution.
• Extensive Toolset – filesystem, shell, code search, testing, building, linting, Git, Docker, HTTP APIs, browser automation, PDF extraction, document generation, database queries, codebase memory, architecture analysis, UI design, and more.
• Optimizations – caching, result compacting, token usage analytics, cost tracking, and context compression to reduce latency and token consumption.
• Secure Token‑Based Access – tokenized URLs for both local and public (Funnel) connections, with easy rotation.
• Deployment Modes – Local Mode (personal machine with Funnel) and Server Mode (VPS behind a reverse proxy, optional OAuth 2.0/PKCE).
• Diagnostic Tools – dana doctor for health checks and dana doctor --json for machine‑readable output.

Use Cases of Dana MCP Server

• Automated Code Review – AI reads pull‑request changes, runs static analysis, tests, and suggests fixes.
• Project‑wide Refactoring – Search symbols, find duplicates, apply batch edits, and commit via Git.
• Continuous Integration Helper – Trigger builds, run coverage, benchmark, and report results back to the chatbot.
• Documentation Generation – Extract PDF content, summarise sections, and produce Markdown/Word/PDF reports.
• Browser‑Based Data Retrieval – Automate login flows, scrape dynamic pages, and feed results to the model.
• Infrastructure Management – Execute Docker commands, inspect containers, query databases, and manage system processes.
• Remote Pair‑Programming – Share the public Funnel URL with a remote AI assistant that can safely operate on your development environment.

FAQ from Dana MCP Server

Q: Do I need Docker to run Dana? A: No. Docker is only one of the supported runtimes. You can use the native installer (python3 install.py) when Docker is unavailable.

Q: How is security enforced? A: Access is controlled by a randomly generated token embedded in the URL and optional OAuth for Server Mode. File‑system access can be limited via config/access_policy.json.

Q: Can multiple AI clients use Dana simultaneously? A: Yes. The server maintains a pool of worker slots (DANA_WORKERS) and can handle concurrent tool calls in parallel.

Q: What if I want the full tool list sent to the client? A: Set the environment variable DANA_PROGRESSIVE_TOOLS=0 to disable progressive discovery.

Q: How do I rotate the authentication token? A: Run python scripts/regenerate_token.py or use the Security panel in Dana Desktop.

Q: Is there a way to monitor usage and costs? A: Dana records token usage and operation analytics; view them in the generated report.html or query via record_token_usage and related tools.

Dana MCP Server

Turn AI chatbots into powerful, free agents that can work with your computer, code, files, projects, and development environment through MCP.

🇮🇷 Persian documentation: README_FA.md
🇬🇧 English: This document

---

🙏 Special Thanks

Special thanks to Mohsen Samadinejad. The original execution idea and early architectural direction that inspired this project came from his work.

His PHP MCP Server was an important behavioral reference during Dana's Python implementation and evolution.

GitHub: Mohsen Samadinejad

---

What is Dana?

Dana is a cross-platform Python MCP server that gives compatible AI chatbots real capabilities on the machine where Dana runs.

Instead of being limited to conversation, a chatbot can become an agent that can:

• read, create, edit, and organize files
• inspect and modify codebases
• run tests, builds, linters, and diagnostics
• manage Git, processes, packages, Docker, databases, and APIs
• automate browsers
• analyze projects and architecture
• work with persistent project memory and optimized context
• extract and analyze PDF content
• generate documents, reports, README files, Word files, and PDFs
• plan, review, debug, and validate engineering work

Dana is designed to work with MCP-compatible AI clients such as ChatGPT, Claude, Grok, and other compatible clients. The core project is free and self-hosted: Dana runs on your own computer or server and performs work there.

Why Dana?

Dana is built around three goals:

1. Real agent capabilities — the chatbot can act through tools instead of only generating text.
2. Self-hosting and control — tools run on infrastructure you control.
3. Efficiency — Progressive Tool Discovery, caching, compact results, batching, and context intelligence reduce unnecessary latency and token usage.

---

Installation and Connection

Download Dana Desktop

For most users, Dana Desktop is the recommended method. Download the latest installer for Windows, Linux, or macOS from the project's GitHub Releases page:

• Download the latest Dana Desktop release
• All Dana releases

The desktop application bundles the Dana setup runtime and provides graphical control for Tailscale, Funnel, connections, runtime, security, and logs.

Method 1 — Dana Desktop (recommended)

After installing Dana Desktop, use the panels in this order:

Setup

• Install Tailscale when it is missing.
• Connect/authenticate Tailscale in the browser.
• Activate Dana.
• Approve and activate Tailscale Funnel when requested.

Dashboard

• View Dana, Tailscale, Funnel, and usage status.

Connections

• Copy the local tokenized MCP URL for software running on the same machine.
• Copy the public tokenized MCP URL when Funnel is active.

Local URL format:

http://127.0.0.1:8765/<TOKEN>/mcp

Public Funnel URL format:

https://<machine>.<tailnet>.ts.net/<TOKEN>/mcp

Runtime

• Start or stop Dana.
• Check the local MCP listener and public route.

Security

• Review authentication and public exposure.
• Copy tokenized connection URLs when needed.

Logs

• Review setup, authentication, Funnel, and runtime events.

After the first installation, the Setup panel uses Activate Dana for normal activation instead of asking you to repeat installation.

When Dana Desktop closes, it stops the Dana runtime and the Funnel route owned by the desktop session.

Method 2 — Terminal / CLI

Use this method when you prefer a terminal or are working on a server.

Docker runtime

Clone the project and install the CLI:

git clone https://github.com/seyed-ali-002/Dana-MCP-Server.git
cd Dana-MCP-Server
python3 -m pip install -e .

Windows:

py -3 -m pip install -e .

Start Dana:

dana run

Useful commands:

dana start
dana stop
dana restart
dana status
dana logs
dana update
dana uninstall

dana run, dana up, and dana start-all prepare the runtime and networking flow.

Tailscale Funnel

For Local Mode, Funnel publishes Dana through HTTPS:

tailscale status
tailscale funnel --https=443 --bg 8765
tailscale funnel status

The connection URL must include Dana's authentication token:

https://<machine>.<tailnet>.ts.net/<TOKEN>/mcp

For local-only access:

http://127.0.0.1:8765/<TOKEN>/mcp

Use dana doctor --show-url when you need the complete tokenized URL in a trusted terminal.

Native runtime

If Docker is unavailable, use the native installer:

Linux/macOS:

python3 install.py

Windows:

py -3 install.py

The native installer configures the runtime, authentication, workers, and deployment mode.

Deployment methods

Local Mode

Local Mode is intended for a personal computer. Dana listens locally and Tailscale Funnel provides the public HTTPS boundary.

AI Client → Tailscale Funnel → Dana → Local machine

Server Mode

Server Mode is intended for a VPS or dedicated server. Dana listens on localhost behind a reverse proxy such as Nginx, Caddy, or Apache.

Internet → Reverse Proxy → 127.0.0.1:<DANA_PORT> → Dana

Server Mode can use the canonical /mcp endpoint with OAuth 2.0 + PKCE. Local Mode uses the tokenized compatibility URL.

Connect an AI client

Use the exact connection URL shown by Dana Desktop under Connections, or the tokenized URL printed by the CLI.

For ChatGPT, Claude, Grok, and other MCP-compatible clients, follow the current custom MCP/connector flow provided by that client. Client menus and availability can change over time.

Important: A tokenized connection URL is a credential. Do not publish it in screenshots, issues, logs, or public documentation.

---

Security and Access Control

Dana executes tools on the machine where it is running. Operating-system permissions therefore matter.

Filesystem access can be restricted in config/access_policy.json:

{
  "allowed_paths": ["/home/user/projects", "/mnt/workspace"],
  "deny_paths": []
}

Dana also provides MCP tools for inspecting and updating the access policy.

Keep connection URLs and tokens private. Rotate a token when necessary:

python scripts/regenerate_token.py

---

Concurrent Workers and Agent Orchestration

Dana supports multiple AI clients and concurrent tool execution in the same MCP service. Worker slots are bounded by DANA_WORKERS, while MCP sessions remain in the stateful transport process so session state is not lost by creating a separate HTTP server for every worker.

Each request is assigned to a worker slot, and independent work can run concurrently. The runtime also supports dependency-aware plans through dana_plan_execute: independent tasks can execute in parallel while dependent tasks wait for their prerequisites.

Useful runtime tools include:

• dana_worker_status — live worker capacity and active/idle slots
• dana_parallel_call — concurrent execution of independent tool calls
• dana_plan_execute — dependency-aware task DAG execution
• dana_runtime_health — registry and orchestration health checks
• dana_workspace_context — compact project/workspace context

This architecture is intended for multiple simultaneous chats without serializing all tool calls behind Worker #1.

Performance and Context Optimization

Dana is intentionally designed to avoid turning a large tool registry into unnecessary prompt overhead.

Progressive Tool Discovery

By default, the MCP client sees a small set of entry points:

• dana_search_tools
• dana_list_tools
• dana_help_tool
• dana_call_tool
• dana_batch_call
• dana_capabilities
• dana_worker_status
• dana_runtime_health
• dana_optimization_stats

The complete registry remains available internally and is discovered on demand. This keeps initial MCP context small even when Dana contains many capabilities.

Runtime Optimization

Dana includes:

• short-lived caching for safe read operations
• parallel execution for independent batch calls
• compact result generation
• context deduplication and compression
• repository and symbol indexing
• delta context and file summaries
• persistent codebase memory
• bounded analysis to avoid oversized responses
• tool cost and optimization statistics

Legacy clients that require the full tool list can disable progressive discovery:

DANA_PROGRESSIVE_TOOLS=0

To disable safe-read caching:

DANA_TOOL_CACHE=0

---

All Dana Capabilities

Dana's complete registry is organized below. In the default optimized MCP mode, these capabilities are discovered and invoked through dana_search_tools and dana_call_tool rather than all being sent to the client at connection time.

Core MCP and Optimization

• dana_search_tools
• dana_call_tool
• dana_batch_call
• dana_capabilities
• dana_optimization_stats
• dana_optimization_controller
• dana_tool_cost
• dana_tool_costs
• dana_fast_path
• dana_prompt_cache_key
• dana_semantic_cache
• dana_result_optimize
• dana_result_page
• dana_result_delta
• dana_context_build
• dana_context_compact

Filesystem and Workspace

• list_directory
• read_file
• write_file
• edit_file
• delete_path
• workspace_snapshot
• change_summary
• rollback_changes
• get_allowed_paths
• set_allowed_paths_tool
• add_allowed_path_tool
• remove_allowed_path_tool
• validate_path_access

Shell, Processes, System, and Network

• run_command
• run_process
• debug_command
• debug_trace
• process_list
• process_stop
• system_info
• system_details
• system_metrics
• environment
• network_check
• port_check
• schedule_command
• cancel_scheduled_task

Code Search and Project Analysis

• search_code
• find_symbol
• find_references
• find_entry_points
• analyze_project
• architecture_summary
• generate_project_diagram
• project_health_check
• code_complexity
• find_duplicate_code
• static_analysis
• python_diagnostics
• change_summary
• analyze_stacktrace
• analyze_implementation_need
• review_implementation
• simplify_code

Build, Test, Quality, and Debugging

• run_tests
• build_project
• discover_tests
• coverage
• benchmark
• check_code_quality
• check_prettier
• lint_or_format
• format_code
• format_project
• format_python
• format_python_check
• lint_python
• fix_python_code
• sort_python_imports
• type_check_python
• lint_javascript
• dana_debug_issue
• dana_test_intelligence
• dana_predict_regression
• dana_rank_root_causes
• dana_self_healing_plan

Git, Packages, Containers, and Dependencies

• git
• package_manager
• dependency_outdated
• dependency_security_scan
• secret_scan
• docker
• docker_status
• docker_build
• container_logs
• toolchain_status

HTTP, APIs, Browser, and Web

• http_request
• api_request
• web_fetch
• browser_check
• browser_open
• browser_automation
• dana_api_intelligence

Optional browser support can be installed with:

pip install -e ".[browser]"
playwright install chromium

Database Intelligence

• sqlite_query
• database_schema
• database_health_check
• dana_database_intelligence

PDF, Documents, Reports, and Documentation

• extract_pdf_text
• extract_pdfs_text
• create_document
• create_docx
• create_pdf
• generate_readme
• generate_changelog
• generate_report

Codebase Memory and Context

• index_codebase
• update_codebase_memory
• clear_codebase_memory
• codebase_memory_status
• search_codebase_memory
• get_context
• get_context_delta
• get_file_delta
• get_file_summary
• get_project_map
• get_symbol_context
• get_dependency_context
• estimate_tokens_for_context
• context_compress
• memory_write
• memory_retrieve
• memory_stats
• memory_digest
• memory_export
• memory_feedback
• memory_link
• memory_links
• memory_maintain
• memory_purge

Library and Documentation Intelligence

• resolve_library
• get_library_docs
• search_library_docs

Advanced Engineering Intelligence

• dana_classify_request
• dana_route_request
• dana_plan
• dana_plan_execute
• dana_create_implementation_plan
• dana_engineering_decision
• dana_engineering_policy
• dana_architecture_review
• dana_dependency_graph
• dana_analyze_change_impact
• dana_project_index
• dana_map_repository
• dana_symbol_search
• dana_trace_symbol
• dana_security_review
• dana_execution_sandbox_plan
• dana_cross_repository_intelligence
• dana_record_architecture_decision
• dana_visual_architecture_graph

Tasks, Planning, and Work Sessions

• create_task_plan
• task_status
• start_work_session
• end_work_session
• dana_session_start
• dana_session_get
• dana_plan_execute
• dana_parallel_call
• dana_workspace_context
• dana_worker_status
• dana_runtime_health

Tool Discovery and Runtime Orchestration

• dana_list_tools
• dana_search_tools
• dana_help_tool
• dana_capabilities
• dana_parallel_call
• dana_plan_execute
• dana_workspace_context
• dana_worker_status
• dana_runtime_health

Token and Operation Analytics

• record_token_usage
• get_token_analytics
• reset_token_analytics
• get_operation_analytics

UI and Visual Design Intelligence

• dana_create_ui_design
• dana_add_ui_screen
• dana_add_ui_component
• dana_connect_ui_screens
• dana_generate_ui_prompt
• dana_export_ui_html

---

Example Requests

After connecting Dana, you can ask your AI client things like:

• “Analyze this repository and explain the architecture.”
• “Find the cause of this stack trace and propose the smallest safe fix.”
• “Read all PDFs in this folder, extract their content, and build a study guide.”
• “Review my changes, predict regression risks, run targeted tests, and report the result.”
• “Create an implementation plan before changing the code.”
• “Search the project for duplicate code and simplify it safely.”
• “Create a Persian Word or PDF report from these project files.”
• “Inspect the database schema and identify likely performance risks.”

---

Dana Doctor

Dana includes a cross-platform diagnostic command for cases where one machine works correctly and another does not.

python -m dana doctor

or:

dana doctor

Doctor checks the Dana version and Git commit, Python compatibility, environment configuration, required project files, dependencies, live health and OAuth routes, Tailscale state, Funnel state, deployment mode, and the generated connector URL. Tokens are masked by default.

python -m dana doctor --show-url

Use --show-url only on a trusted terminal when you need the complete Local Mode URL. Machine-readable output is also available:

python -m dana doctor --json

MCP Connection & Authentication

Dana keeps its authentication token persistent across runtime restarts. A token changes only after an explicit token action from the Control Center or the token regeneration scripts.

In Local Mode, the Control Center exposes a tokenized Streamable HTTP URL:

https://<tailscale-host>/<token>/mcp

This URL is the direct connection credential and is intended for MCP clients that accept a URL-only connection. Dana also accepts the standard Authorization: Bearer <token> header on the canonical /mcp endpoint and on the tokenized endpoint.

The Control Center's Connections view includes a live connection test. The Security view supports both random token generation and custom token replacement. Rotating a token invalidates previously issued tokenized URLs.

Path access can be configured with DANA_ALLOWED_PATHS and DANA_DENIED_PATHS. Use one path per line. An empty allowed list means all paths are allowed unless denied; denied paths always take precedence.

---

Usage Report and Observability

Dana generates a local report.html containing token estimates/provider-reported usage, operation counts, worker activity, failures, and actual tool execution time. Active usage time sums the measured execution duration of operations; idle time between separate chats is not counted as usage.

Runtime databases, reports, and local telemetry are kept out of Git.

Testing

Run the test suite:

pytest -q

For a basic syntax check:

python3 -m py_compile dana/http.py

---

Architecture

Dana keeps the MCP layer lightweight while heavier analysis is performed on demand:

AI Client
   │
   ▼
Dana MCP Gateway
   │
   ├── Progressive Tool Discovery
   ├── Authentication / OAuth
   ├── Optimization Layer
   └── Tool Router
          │
          ├── System & Files
          ├── Engineering Intelligence
          ├── Codebase Memory
          ├── Browser & API
          ├── Documents & PDF
          └── Database & Containers

This design helps Dana grow without sending its entire capability set into every initial MCP request.

---

Contributing

Dana is an open project and contributions are welcome.

You can help by:

1. reporting bugs
2. proposing new tools or integrations
3. improving installation and deployment support
4. adding tests
5. improving documentation
6. submitting pull requests
7. reviewing architecture and performance

Before opening a pull request, please test your changes and keep changes focused where possible.

When reporting a bug, include relevant information such as:

• operating system
• Python version
• Dana version or commit
• deployment mode
• relevant logs
• reproduction steps

If Dana is useful to you, consider starring the repository and sharing ideas for its next capabilities.

License

See LICENSE.